From 56f9f42836d8eea7224188604eef13890d720c84 Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 22:29:58 +0100 Subject: [PATCH 01/11] Add automatic deployment from 'master' to 'gh-pages'. Using @domenic's guide: https://gist.github.com/domenic/ec8b0fc8ab45f39403dd --- .gitignore | 1 + .travis.yml | 8 + deploy.sh | 63 +++ deploy_key.enc | Bin 0 -> 3248 bytes index.bs | 894 ------------------------------------ published/FPWD.html | 1071 ------------------------------------------- 6 files changed, 72 insertions(+), 1965 deletions(-) create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 deploy.sh create mode 100644 deploy_key.enc delete mode 100644 index.bs delete mode 100644 published/FPWD.html diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8f00ed6 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +deploy_key diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..42f58a4 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +language: generic + +script: bash ./deploy.sh + +env: + global: + - ENCRYPTION_LABEL: 104fbe69e8fa + - COMMIT_AUTHOR_EMAIL: travis-ci@w3.org diff --git a/deploy.sh b/deploy.sh new file mode 100644 index 0000000..be8e31e --- /dev/null +++ b/deploy.sh @@ -0,0 +1,63 @@ +#!/bin/bash +set -e # Exit with nonzero exit code if anything fails + +SOURCE_BRANCH="master" +TARGET_BRANCH="gh-pages" + +function doCompile { + curl https://api.csswg.org/bikeshed/ -f -F file=@index.bs > index.html; +} + +# Pull requests and commits to other branches shouldn't try to deploy, just build to verify +if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then + echo "Skipping deploy; just doing a build." + doCompile + exit 0 +fi + +# Save some useful information +REPO=`git config remote.origin.url` +SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:} +SHA=`git rev-parse --verify HEAD` + +# Clone the existing gh-pages for this repo into out/ +# Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deply) +git clone $REPO out +cd out +git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH +cd .. + +# Clean out existing contents +rm -rf out/**/* || exit 0 + +# Run our compile script +doCompile + +# Now let's go have some fun with the cloned repo +cd out +git config user.name "Travis CI" +git config user.email "$COMMIT_AUTHOR_EMAIL" + +# If there are no changes to the compiled out (e.g. this is a README update) then just bail. +if [ -z `git diff --exit-code` ]; then + echo "No changes to the output on this push; exiting." + exit 0 +fi + +# Commit the "changes", i.e. the new version. +# The delta will show diffs between new and old versions. +git add . +git commit -m "Deploy to GitHub Pages: ${SHA}" + +# Get the deploy key by using Travis's stored variables to decrypt deploy_key.enc +ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key" +ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv" +ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR} +ENCRYPTED_IV=${!ENCRYPTED_IV_VAR} +openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in deploy_key.enc -out deploy_key -d +chmod 600 deploy_key +eval `ssh-agent -s` +ssh-add deploy_key + +# Now that we're all set up, we can push. +git push $SSH_REPO $TARGET_BRANCH diff --git a/deploy_key.enc b/deploy_key.enc new file mode 100644 index 0000000000000000000000000000000000000000..72f382850da84d90b8e935c876837cf925137aec GIT binary patch literal 3248 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 -Title: Permissions -Repository: w3c/permissions -Status: ED -ED: https://w3c.github.io/permissions/ -TR: https://www.w3.org/TR/permissions/ -Shortname: permissions -Level: 1 -Group: webappsec -Editor: Mounir Lamouri, Google Inc. https://google.com/ -Editor: Marcos Cáceres, Mozilla https://mozilla.com/ -Editor: Jeffrey Yasskin, Google Inc. https://google.com/ - -Abstract: The Permissions Standard defines common infrastructure for other specifications that need to interact with browser permissions. It also defines an API to allow web applications to query and request changes to the status of a given permission. -Mailing List: public-webappsec@w3.org -Mailing List Archives: http://lists.w3.org/Archives/Public/public-webappsec/ - -!Participate: We are on Github. -!Participate: File a bug. -!Participate: Commit history. -!Implementation status: Blink/Chromium -!Implementation status: Gecko - -Markup Shorthands: css no, markdown yes - -
-spec: ECMAScript; urlPrefix: https://tc39.github.io/ecma262/#
-    type: interface
-        text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
-spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
-    type: dfn
-        text: origin; url: browsers.html#origin-2
-spec: promises-guide; urlPrefix: https://www.w3.org/2001/tag/doc/promises-guide#
-    type: dfn
-        text: Transforming; url: transforming-by
-        text: Promise-calling; url: promise-calling
-
-
-spec: html
-    type: dfn
-        text: browsing context
-        text: environment settings object
-        text: event handler
-        text: event handler event type
-        text: origin
-        text: parent browsing context
-        text: queue a task
-        text: top-level browsing context
-spec: ui-events
-    type: dfn
-        text: user agent
-spec: webidl
-    type: interface
-        text: Promise
-
- -
-

- Scope of this document -

-

This section is non-normative.

-

- This document's goal is to specify an API that will help developers to - handle permissions on the Web platform. Web APIs have different ways to - deal with permissions. The [[notifications]] API allows developers to - request a permission and check the permission status explicitly. Others - might only expose the status to web pages when they try to use the API, - like the [[geolocation-API]] which fails if the permission was not - granted without allowing the developer to check beforehand. -

-

- Being able to know whether an API call is going to prompt is useful in - order to provide a good user experience. Unfortunately, more often than - not, those prompts can't be controlled by developers. -

-

- The API specified in this document is meant to provide the tools so - that web applications can improve their user experience when - permissions are involved. -

-

- The solution described in this document is meant to be extensible but - isn't meant to be applicable to all the current and future permissions - available in the web platform. If you are working on a specification - that has a permission model that wouldn't fit in the model described in - this document, please contact the editors or file an issue. We would - love to hear about it. -

-
-
-

- Privacy considerations -

-

This section is non-normative.

-

- Permission states can be used as an element of fingerprinting by - websites. Usually websites could already have access to the information - but often through actually using the API which could lead to a - permission request UI if the permission was not already granted. Thus, - even though this API doesn't expose new fingerprinting data to - websites, it makes it easier for them to have discreet access to it. - Therefore, implementations are encouraged to have an option for users - to block (globally or selectively) the querying of permission states. -

-
-
-

- Permission descriptor -

- 
-    dictionary PermissionDescriptor {
-      required PermissionName name;
-    };
-
-

- A permission is described by a name and other properties that depend on the - name. The simplest permissions require only a name, but some others have - more detailed structure that requires more information to describe it. In - that case, they should define a customized permission descriptor - type dictionary that inherits from {{PermissionDescriptor}}. -

-
-
-

- Permission Registry -

- 
-    enum PermissionName {
-      "geolocation",
-      "notifications",
-      "push",
-      "midi",
-      "camera",
-      "microphone",
-      "speaker",
-      "device-info",
-      "background-sync",
-      "bluetooth",
-    };
-
-

- Each enumeration value in the {{PermissionName}} enum identifies a - permission, which consists of the following - algorithms and types: -

-
-
- A permission descriptor type -
-
- {{PermissionDescriptor}} or one of its subtypes. - If unspecified, this defaults to {{PermissionDescriptor}}. -
-
- A permission storage type -
-
- {{PermissionStorage}} or one of its subtypes. - If unspecified, this defaults to {{PermissionStorage}}. -
-
- A permission result type -
-
- {{PermissionStatus}} or one of its subtypes. - If unspecified, this defaults to {{PermissionStatus}}. -
-
- A permission query algorithm -
-
- Takes an instance of the permission descriptor type, - an instance of the permission storage type that's currently - stored for this permission, and a new or existing instance of - the permission result type, and updates the permission - result type instance with the query result. Used by - {{Permissions}}' {{Permissions/query()}} - method and the PermissionStatus - update steps. If unspecified, this defaults to the boolean - permission query algorithm. -
-
- A permission request algorithm -
-
- Takes the previously-stored instance of the permission storage - type, an instance of the permission descriptor type, - and a newly-created instance of the permission result type. - Shows the user any necessary prompt to try to increase permissions, - and updates the instances of the permission storage type and - permission result type to match. May return a {{Promise}} - if the request can fail exceptionally. (Merely being denied - permission is not exceptional.) Used by {{Permissions}}' - {{Permissions/request()}} method, which handles - reading and writing the permission store. If unspecified, this - defaults to the boolean permission request algorithm. -
-
- A permission revocation algorithm -
-
- Takes no arguments. Updates any other parts of the implementation - that need to be kept in sync after an entry is removed from the - permission store. Triggered by {{Permissions}}' - {{Permissions/revoke()}} method. If unspecified, this - defaults to doing nothing. -
-
-

- A boolean permission is a permission with all types - and algorithms defaulted. -

-
-

- Geolocation -

-

- The "geolocation" - permission is the permission associated with the usage of the - [[geolocation-API]]. It is a boolean permission. -

-
-
-

- Notifications -

-

- The "notifications" - permission is the permission associated with the usage of the - [[notifications]] API. It is a boolean permission. -

-
-
-

- Push -

-

- The "push" - permission is the permission associated with the usage of the - [[push-api]]. -

-
-
- permission descriptor type -
-
- 
-          dictionary PushPermissionDescriptor : PermissionDescriptor {
-            boolean userVisibleOnly = false;
-          };
-
-
-
-
-
-

- Midi -

-

- The "midi" - permission is the permission associated with the usage of - [[webmidi]]. -

-
-
- permission descriptor type -
-
- 
-          dictionary MidiPermissionDescriptor : PermissionDescriptor {
-            boolean sysex = false;
-          };
-
-
-
-
-
-

- Media Devices -

-

- The "camera", "microphone" , and - "speaker" - permissions are associated with permission to use media devices as - specified in [[GETUSERMEDIA]] and [[audio-output]]. -

-
-
- permission descriptor type -
-
- 
-          dictionary DevicePermissionDescriptor : PermissionDescriptor {
-            DOMString deviceId;
-          };
-
-

- A permission covers access to the device given in the associated - descriptor. -

-

- If the descriptor does not have a {{deviceId}}, its semantic is that - it queries for access to all devices of that class. Thus, if a - query for the {{"camera"}} permission with no {{deviceId}} returns - {{"granted"}}, the client knows that there will never be a permission - prompt for a camera, and if {{"denied"}} is returned, it knows that - no getUserMedia request for a camera will succeed. -

-

- If a permission state is present for access to some, but not all, - cameras, a query without the {{deviceId}} will return {{"prompt"}}. -

-
-
- permission storage type -
-
- TODO -
-
- permission result type -
-
- TODO -
-
- permission query algorithm -
-
- TODO -
-
- permission request algorithm -
-
- TODO -
-
- permission revocation algorithm -
-
- TODO: Stop playing/recording data? -
-
-

- The "device-info" - permission controls access to names and capabilities of input and - output devices. -

-

- A successful call to the getUserMedia function of - [[GETUSERMEDIA]] MUST cause permission to be granted for the returned - devices, and MAY cause other permissions to be granted. -

-

- Stopping a MediaStreamTrack MAY cause permission to be revoked for - the associated device. -

-
-
-

- Background Sync -

-

- The "background-sync" - permission is the permission associated with the usage of - [[web-background-sync]]. -

-
-
-
-

- Permission Store -

-

- User agents MAY use a form of storage to - keep track of web site permissions. When they do, they MUST have a - permission storage identifier which is linked to a - {{PermissionStorage}} instance or one of its subtypes. -

-

- To get a permission storage identifier for a - {{PermissionName}} name and an environment settings - object settings, the UA MUST return a tuple consisting - of: -

-
    -
  1. - name -
    2. -
  2. - settings' origin -
    3. -
  3. optional UA-specific data like whether settings' - browsing context has a parent browsing context, or - settings' top-level browsing context's origin -
    4. -
- 
-    dictionary PermissionStorage {
-      // PermissionStorage is just an explanatory device.
-      // Instances are never received from or passed to Javascript code.
-
-      required PermissionState state;
-    };
-
-

- The steps to retrieve a permission storage entry of a - permission storage identifier are as follows: -

-
    -
  1. If the user agent has a {{PermissionStorage}} associated - with the permission storage identifier in its permission store, - it MUST return the {{PermissionStorage}}. -
    2. -
  2. Otherwise, it MUST return undefined. -
    3. -
-

- The steps to create a permission storage entry for a - permission storage identifier are as follows: -

-
    -
  1. If the user agent has a {{PermissionStorage}} associated - with the permission storage identifier in its permission store, - it MUST overwrite it to the given {{PermissionStorage}}. -
    2. -
  2. Otherwise, it MUST write the new {{PermissionStorage}} to its - permission store. -
    3. -
-

- The steps to delete a permission storage entry of a - permission storage identifier are as follows: -

-
    -
  1. If the user agent has a {{PermissionStorage}} associated - with the permission storage identifier in its permission store, - it MUST remove it. -
    2. -
-
-
-

- Status of a permission -

- 
-    enum PermissionState {
-      "granted",
-      "denied",
-      "prompt",
-    };
-
-

- The "granted" state represents - that the caller will be able - to successfuly access the feature without having the user agent - asking the user's permission. -

-

- The "denied" state represents - that the caller will not be - able to access the feature. -

-

- The "prompt" state represents - that the user agent - will be asking the user's permission if the caller tries to access the - feature. The user might grant, deny or dismiss the request. -

-

- The steps to retrieve the permission storage for a given - {{PermissionName}} name are as follows: -

-
    -
  1. - Get a permission storage identifier for name and - the current environment settings object, and let - identifier be the result. -
    2. -
  2. Run the steps to retrieve a permission storage entry of - identifier. -
    3. -
  3. If the result of those steps are not undefined, return - it and abort these steps. -
    4. -
  4. Otherwise, the user agent MUST return a default value based - on user agent's defined heuristics. For example, {state: - {{"prompt"}}} can be a default value, but it can also be based on - frequency of visits. -
    5. -
- 
-    [Exposed=(Window,Worker)]
-    interface PermissionStatus : EventTarget {
-      readonly attribute PermissionState state;
-      attribute EventHandler onchange;
-    };
-
-

- {{PermissionStatus}} instances are created with the following - internal slots: -

-
-
- \[[permission]] -
-
- A permission. {{[[permission]]}} is always the - permission named {{[[query]]}}.{{PermissionDescriptor/name}}. -
-
- \[[query]] -
-
- A {{PermissionDescriptor}}. -
-
-

- The steps to update the state of a - {{PermissionStatus}} instance status are as - follows: -

-
    -
  1. Run the steps to retrieve the permission storage for - status@{{[[query]]}}.{{PermissionDescriptor/name}}, - and let storage be the result. -
    2. -
  2. Run status@{{[[permission]]}}'s permission - query algorithm, passing status@{{[[query]]}}, - storage, and status. -
    3. -
-

- The steps to create a PermissionStatus for a given - {{PermissionDescriptor}} permissionDesc are as follow: -

-
    -
  1. Let permission be the permission named by - permissionDesc.name. -
    2. -
  2. Let status be a new instance of permission's - permission result type, with the internal slots filled as: - - - - - - - - - - - - - - - -
    - Slot - - Value -
    - {{PermissionStatus/[[permission]]}} - - permission -
    - {{PermissionStatus/[[query]]}} - - permissionDesc -
    -
    3. -
  3. Return status. -
    4. -
-

- The state - attribute MUST return the latest value that was set on the current - instance. -

-

- The onchange attribute is an - event handler whose corresponding event handler event - type is change. -

-

- Whenever the user agent is aware that the state of a - {{PermissionStatus}} instance status has changed, - it MUST asynchronously run the following steps: -

-
    -
  1. Run the steps to update the state of status. -
    2. -
  2. - Queue a task on the permission task source to - fire an event named change at - status. -
    3. -
-
-
- -

- A {{Permissions}} instance is exposed on the navigator - object for {{Window}} and {{Worker}} contexts. -

- 
-    [Exposed=(Window)]
-    partial interface Navigator {
-      readonly attribute Permissions permissions;
-    };
-
- 
-    [Exposed=(Worker)]
-    partial interface WorkerNavigator {
-      readonly attribute Permissions permissions;
-    };
-
-
-
-

- Permissions interface -

- 
-    [Exposed=(Window,Worker)]
-    interface Permissions {
-      Promise<PermissionStatus> query(PermissionDescriptor permissionDesc);
-
-      Promise<PermissionStatus> request(PermissionDescriptor permissionDesc);
-
-      Promise<PermissionStatus> revoke(PermissionDescriptor permissionDesc);
-    };
-
-

- When the query() method is invoked, - the user agent MUST run the following query a - permission algorithm, passing the parameter - permissionDesc: -

-
    -
  1. If permissionDesc.name has a permission - descriptor type other than {{PermissionDescriptor}}, convert the - underlying ECMAScript object to the permission descriptor type - dictionary as - described in - [[!WEBIDL]], then: -
      -
    • If that operation failed, return a {{Promise}} rejected with - a {{TypeError}} and abort these steps. -
      • -
    • Otherwise, set permissionDesc to the result of the - operation. -
      • -
    -
    2. -
  2. Let promise be a newly-created {{Promise}}. -
    3. -
  3. Return promise and continue the following steps - asynchronously. -
    4. -
  4. Run the steps to create a PermissionStatus for - permissionDesc, and let status be the result. -
    5. -
  5. Run the steps to update the state on status. -
    6. -
  6. Resolve promise with status. -
    7. -
-
- If a developer wants to check multiple permissions at once, the editors - recommend the use of {{Promise}}.all(). An example can be - found in the Examples section. -
-

- When the request() method is invoked, - the user agent MUST run the following request a - permission algorithm, passing the parameter - permissionDesc: -

-
    -
  1. If permissionDesc.name has a permission - descriptor type other than {{PermissionDescriptor}}, convert the - underlying ECMAScript object to the permission descriptor type - dictionary as - described in - [[!WEBIDL]], then: -
      -
    • If that operation failed, return a {{Promise}} rejected with - a {{TypeError}} and abort these steps. -
      • -
    • Otherwise, set permissionDesc to the result of the - operation. -
      • -
    -
    2. -
  2. Let promise be a newly-created {{Promise}}. -
    3. -
  3. Return promise and continue the following steps - asynchronously. -
    4. -
  4. Let permission be the permission named by - permissionDesc.name. -
    5. -
  5. Run the steps to create a PermissionStatus for - permissionDesc, and let status be the result. -
    6. -
  6. Run the steps to retrieve the permission storage for - permission, and let storage be the result. -
    7. -
  7. Let result be the result of promise-calling - permission's permission request algorithm with - storage, permissionDesc, and status - as arguments. -
    8. -
  8. Resolve promise with the result of transforming - result with a fulfillment handler that runs the following - steps. -
    9. -
  9. - Get a permission storage identifier for - permissionDesc.name and the current - environment settings object, and create a permission - storage entry mapping this identifier to storage. -
    10. -
  10. Return status. -
    11. -
-

- When the revoke() - method is invoked, the user agent MUST run the following - revoke a permission algorithm, passing the - parameter permissionDesc: -

-
    -
  1. If permissionDesc.name has a permission - descriptor type other than {{PermissionDescriptor}}, convert the - underlying ECMAScript object to the permission descriptor type - dictionary as - described in - [[!WEBIDL]], then: -
      -
    • If that operation failed, return a {{Promise}} rejected with - a {{TypeError}} and abort these steps. -
      • -
    • Otherwise, set permissionDesc to the result of the - operation. -
      • -
    -
    2. -
  2. Let promise be a newly-created {{Promise}}. -
    3. -
  3. Return promise and continue the following steps - asynchronously. -
    4. -
  4. - Get a permission storage identifier for - permission.name and the current - environment settings object, and let identifier be - the result. -
    5. -
  5. Run the steps to delete a permission storage entry using - identifier. -
    6. -
  6. Run permissionDesc.name's permission revocation - algorithm. -
    7. -
  7. Run the steps to create a PermissionStatus for - permissionDesc, and let status be the result. -
    8. -
  8. Run the steps to update the state on status. -
    9. -
  9. Resolve promise with status. -
    10. -
-
-
-

- Common permission algorithms -

-

- The boolean permission query algorithm, given a - {{PermissionDescriptor}} permissionDesc, a - {{PermissionStorage}} storage, and a - {{PermissionStatus}} status, runs the following steps: -

-
    -
  1. Set status.state to - storage.state -
    2. -
-

- The boolean permission request algorithm, given a - {{PermissionDescriptor}} permission and a - {{PermissionStatus}} status, runs the following steps: -

-
    -
  1. TODO -
    2. -
-
-
-

- Examples -

-
-

- This example uses the Permissions API to decide whether local news - should be shown using the Geolocation API or with a button offering to - add the feature. -

- 
-    <script>
-      navigator.permissions.query({name:'geolocation'}).then(function(result) {
-        if (result.state == 'granted') {
-          showLocalNewsWithGeolocation();
-        } else if (result.state == 'prompt') {
-          showButtonToEnableLocalNews();
-        }
-        // Don't do anything if the permission was denied.
-      });
-    </script>
-
-
-
-

- This example is using the {{"notifications"}} permission for a - chat application to show a notification button depending on the - permission state. -

- 
-    <script>
-      function updateNotificationButton(state) {
-        document.getElementById('chat-notification-button').disabled = (state == 'denied');
-      }
-
-      navigator.permissions.query({name:'notifications'}).then(function(result) {
-        updateNotificationButton(result.state);
-
-        result.addEventListener('change', function() {
-          updateNotificationButton(this.state);
-        });
-      });
-    </script>
-
-
-
-

- This example is checking whether the page has the - {{"geolocation"}} and the {{"notifications"}} permissions - using {{Promise}}.all. -

- 
-    <script>
-      Promise.all([navigator.permissions.query({name:'geolocation'}),
-                   navigator.permissions.query({name:'notifications'})])
-      .then(function(result) {
-        console.log('Geolocation permission state is ' + result[0].state);
-        console.log('Notifications permission state is ' + result[1].state);
-      });
-    </script>
-
-
-
-

- This example is checking whether the page has the {{"camera"}} - permission for the first device in the list. Error checking omitted. -

- 
-    <script>
-      navigator.mediaDevices.enumerateDevices()
-      .then(function(devices) {
-         return navigator.permissions.query({name:'camera',
-                                             deviceId: devices[0].deviceId})
-      })
-      .then(function(result) {
-         console.log('Camera permission to first camera is ' + result.state);
-      }
-      .catch(err => console.log('Bad things happened: ' + err.name));
-    </script>
-
-
-
-
-

- Acknowledgments -

-

- The editors would like to thank Adrienne Porter Felt, Anne van - Kesteren, Domenic Denicola, Jake Archibald and Wendy Seltzer for their - help with the API design and editorial work. -

-
diff --git a/published/FPWD.html b/published/FPWD.html deleted file mode 100644 index 2966fa0..0000000 --- a/published/FPWD.html +++ /dev/null @@ -1,1071 +0,0 @@ - - - - - The Permissions API - - - - - - -

Abstract

- The Permissions API allows a web application to be aware of - the status of a given permission, to know whether it is granted, denied - or if the user will be asked whether the permission should be granted. -

Status of This Document

- - - -

- This section describes the status of this document at the time of its publication. - Other documents may supersede this document. A list of current W3C publications and the - latest revision of this technical report can be found in the W3C technical reports index at - http://www.w3.org/TR/. -

- -

- This document was published by the Web Application Security Working Group as a First Public Working Draft. - - This document is intended to become a W3C Recommendation. - - - If you wish to make comments regarding this document, please send them to - public-webappsec@w3.org - (subscribe, - archives). - - - - - - - All comments are welcome. - - -

- - - -

- Publication as a First Public Working Draft does not imply endorsement by the W3C - Membership. This is a draft document and may be updated, replaced or obsoleted by other - documents at any time. It is inappropriate to cite this document as other than work in - progress. -

- - - -

- - This document was produced by a group operating under the - 5 February 2004 W3C Patent - Policy. - - - - - W3C maintains a public list of any patent - disclosures - - made in connection with the deliverables of the group; that page also includes - instructions for disclosing a patent. An individual who has actual knowledge of a patent - which the individual believes contains - Essential - Claim(s) must disclose the information in accordance with - section - 6 of the W3C Patent Policy. - - -

- -

This document is governed by the 1 August 2014 W3C Process Document. -

- - - - - -

Table of Contents

- -

1. Conformance

-

- As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, - and notes in this specification are non-normative. Everything else in this specification is - normative. -

-

The key words MAY, MUST, and RECOMMENDED are - to be interpreted as described in [RFC2119]. -

- -

- This specification defines conformance criteria that apply to a single - product: the user agent that implements the interfaces that - it contains. -

-

- Implementations that use ECMAScript to expose the APIs defined in this - specification MUST implement them in a manner consistent with the - ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. -

-
-
-

2. - Dependencies -

-

- The following concepts and interfaces are defined in [HTML]: -

- -

- - Promise objects are defined in [ECMASCRIPT]. -

-
-
-

3. - Scope of this document -

This section is non-normative.

-

- This document goal is to specify an API that will help developers to - handle permissions on the Web platform. Web APIs have different ways to - deal with permissions. The [notifications] API allows developers to - request a permission and check the permission status explicitly. Others - might only expose the status to web pages. Some, like [geolocation-API] - will keep the page unaware of the permission associated with the - feature. -

-

- Being able to know whether an API call is going to prompt is mandatory - in order to provide a good user experience. Unfortunately, more often - than not, those prompts can't be controlled by the developers. -

-

- The API specified in this document is meant to provide the tools so - that web applications can improve their user experience when - permissions are involved. -

-

- The solution described in this document is meant to be extensible but - isn't meant to be applicable to all the current and future permissions - available in the web platform. If you are working on a specification - that has a permission model that wouldn't fit in the model described in - this document, please contact the editors or file an issue. We would - love to hear about it. -

-

- The initial intent of this document was to allow web applications to - request and revoke permissions explicitly in addition of query the - permission status. This is an aspect of the specification that was - controversial thus removed from the current document in a spirit of - incremental changes: settling on a small API that can be improved. -

-
-
-

4. - Permission Registry -

- 
enum PermissionName {
-    "geolocation",
-    "notifications",
-    "push-notifications",
-    "midi-sysex"
-};
-

- The PermissionName enum defines the list of known - permissions. These permissions are meant to be associated with a use - case instead of one API. Thus, some permissions have a 1:1 relationship - with an API while some others might include more than one API or even a - subset of an API. -

-
Note

- For example, push-notifications is exposing the ability for a - web page to use push messages in order to show notifications. - Implementations might associate it with full usage of the Push API and - the Notifications API while others will force the callers to use the - Push API only in order to use the Notifications API. -

-

- Specifications are welcome to request a new name to be added to this - registry instead of trying to monkey patch it. -

-

- The geolocation - permission is the permission associated with the usage of the - [geolocation-API]. -

-

- The notifications - permission is the permission associated with the usage of the - [notifications] API. -

-

- The push-notifications - permission is the permission associated with the usage of the - [push-api] in order to show notifications using the [notifications] - API. -

-

- The midi-sysex permission - is the permission associated with the usage of sysex messages in the - [webmidi] API. -

-
-
-

5. - Permission definition -

- 
dictionary Permission {
-    required PermissionName name;
-};
-

- A Permission dictionary MUST contain a name field which represents the - permission's identifier. -

-

- If a permission has to be defined by more than its name, it is - RECOMMENDED to inherit from Permission dictionary and add - new fields. -

-
Note
- There are currently no permission defined in this specification using - this dictionary. It is only specified here in order to expose the - ability for the API to be extended to more complex permissions.
- For example, if the [quota-api] were to have an associated - permission, it could define a QuotaPermission dictionary extending - Permission with type and value fields. -
-
-
-

6. - Status of a permission -

- 
enum PermissionState {
-    "granted",
-    "denied",
-    "prompt"
-};
-

- The steps to retrieve the permission state of a global - object for a given permission are as follows: -

-
    -
  1. If the user agent will allow the global object to try - to access the features associated with the permission but - will prompt the user to know whether the call should succeed or fail, - the user agent MUST return prompt. -
    2. -
  2. Otherwise, if the user agent will allow the global - object to access the features associated with the - permission without prompting the user, the user - agent MUST return granted . -
    3. -
  3. Otherwise, the user agent will not allow the global - object to access the feature associated with - permission and MUST return denied . -
    4. -
-

- How the user agent decides whether a global object is - allowed or not to access some features is left as an implementation - details. However, the implementation MUST be consistent and not return - different values unless something happened (user action, expiration). -

-

- It is RECOMMENDED for implementations to use the origins of the Document or Worker when - making security decisions. Other factors MAY also apply like whether - the permission is associated with a [powerful-features] or whether - the Document is embedded. -

-
Issue 1
- The retrieve the permission state algorithm does not take into - account all the theoretically possible use cases. It tries to stay - inside the scope of the permissions described in this document.
- There are open questions about use cases where it might not work as - well: issue 8 - and issue 9. -
- 
[Exposed=(Window,Worker)]
-interface PermissionStatus : EventTarget {
-    readonly    attribute Permission      permission;
-    readonly    attribute PermissionState status;
-                attribute EventHandler    onchange;
-};
-

- The steps to update the status of a - PermissionStatus instance are as follow: -

-
    -
  1. Let status be the PermissionStatus instance - being updated. -
    2. -
  2. Run the steps to retrieve the permission state using the - status' global object and permission - attribute then set the result of those steps to the status - attribute. -
    3. -
-

- The steps to create a PermissionStatus for a given - permission are as follow: -

-
    -
  1. Let status be a PermissionStatus instance. -
    2. -
  2. Set the permission attribute to - permission. -
    3. -
  3. Run the steps to update the status on status. -
    4. -
  4. Return status. -
    5. -
-

- The permission attribute - MUST return the Permission it was initially set to - at the object creation. -

-

- The status - attribute MUST return the latest value that was set while running the - update the status steps on the current instance. -

-

- The onchange attribute is an - event handler whose corresponding event handler event - type is change. -

-

- Whenever the user agent is aware that the status of - a PermissionStatus instance has changed, it MUST - asynchronously run the following steps: -

-
    -
  1. Let permission-status be the - PermissionStatus for which the status has - changed. -
    2. -
  2. Run the steps to update the status of - permission-status. -
    3. -
  3. - Queue a task on the permission task source to - fire a simple event named change at - permission-status. -
    4. -
-
-
-

7. - Permissions interface -

- 
[Exposed=(Window,Worker)]
-interface Permissions {
-    static Promise<PermissionStatus> query ((Permission or PermissionName) permission);
-};
-

- When the - query() method is invoked, the user agent MUST run - the following steps: -

-
    -
  1. Let permission be permission argument if - permission is of type Permission, otherwise, - create a Permission instead for which name is - set to the permission argument value. -
    2. -
  2. Let promise be a newly-created Promise. -
    3. -
  3. Return promise and continue those steps asynchronously. -
    4. -
  4. Run the steps to create a PermissionStatus using the - global object and permission and resolve - promise with the result of those steps. -
    5. -
-
Note
- If a developer wants to check multiple permissions at once, the editors - recommend them to use Promises.all(). It should yield to the same - result and allow this API to stay simple. If it happens to be a very - common use case, it should be easy to extend Permissions.query() to - accept a sequence<> too. -
-
-
-

8. - Examples -

This section is non-normative.

-

- This example uses the Permissions API to decide whether local news - should be shown using the Geolocation API or a button offering that - feature should be added. -

-
Example 1
<script>
-  Permissions.query('geolocation').then(function(result) {
-    if (result.status == 'granted') {
-      showLocalNewsWithGeolocation();
-    } else if (result.status == 'prompt') {
-      showButtonToEnableLocalNews();
-    }
-    // Don't do anything if the permission was denied.
-  });
-</script>
-

- This example is using the notifications permission for a - chat application to show a notification button depending on the - permission status. -

-
Example 2
<script>
-  function updateNotificationButton(permission) {
-    document.getElementById('chat-notification-button').disabled = (permission.status == 'denied');
-  }
-
-  Permissions.query('notifications').then(function(result) {
-    updateNotificationButton(result);
-
-    result.addEventListener('change', function() {
-      updateNotificationButton(this);
-    });
-  });
-</script>
-
- -
-

A. - Acknowledgments -

-

- Thanks to Adrienne Porter Felt and Jake Archibald for their early - support and help. -

-
- - -

B. References

B.1 Normative references

[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification, Edition 6. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html -
[HTML]
Ian Hickson. HTML. Living Standard. URL: https://html.spec.whatwg.org/ -
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 -
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/ -

B.2 Informative references

[geolocation-API]
Andrei Popescu. Geolocation API Specification. 24 October 2013. W3C Recommendation. URL: http://www.w3.org/TR/geolocation-API/ -
[notifications]
John Gregg; Anne van Kesteren. Web Notifications. 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/notifications/ -
[powerful-features]
Mike West. Requirements for Powerful Features. 4 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/powerful-features/ -
[push-api]
Bryan Sullivan; Eduardo Fullea; Michael van Ouwerkerk. Push API. 7 October 2014. W3C Working Draft. URL: http://www.w3.org/TR/push-api/ -
[quota-api]
Kinuko Yasuda. Quota Management API. 5 November 2013. W3C Working Draft. URL: http://www.w3.org/TR/quota-api/ -
[webmidi]
Chris Wilson; Jussi Kalliokoski. Web MIDI API. 17 March 2015. W3C Working Draft. URL: http://www.w3.org/TR/webmidi/ -
From 4c3523c9626f75ea55ebfa8605453f78aa7d4af8 Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 22:38:32 +0100 Subject: [PATCH 02/11] Revert "Add automatic deployment from 'master' to 'gh-pages'." This reverts commit 56f9f42836d8eea7224188604eef13890d720c84. --- .gitignore | 1 - .travis.yml | 8 - deploy.sh | 63 --- deploy_key.enc | Bin 3248 -> 0 bytes index.bs | 894 ++++++++++++++++++++++++++++++++++++ published/FPWD.html | 1071 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 1965 insertions(+), 72 deletions(-) delete mode 100644 .gitignore delete mode 100644 .travis.yml delete mode 100644 deploy.sh delete mode 100644 deploy_key.enc create mode 100644 index.bs create mode 100644 published/FPWD.html diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 8f00ed6..0000000 --- a/.gitignore +++ /dev/null @@ -1 +0,0 @@ -deploy_key diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 42f58a4..0000000 --- a/.travis.yml +++ /dev/null @@ -1,8 +0,0 @@ -language: generic - -script: bash ./deploy.sh - -env: - global: - - ENCRYPTION_LABEL: 104fbe69e8fa - - COMMIT_AUTHOR_EMAIL: travis-ci@w3.org diff --git a/deploy.sh b/deploy.sh deleted file mode 100644 index be8e31e..0000000 --- a/deploy.sh +++ /dev/null @@ -1,63 +0,0 @@ -#!/bin/bash -set -e # Exit with nonzero exit code if anything fails - -SOURCE_BRANCH="master" -TARGET_BRANCH="gh-pages" - -function doCompile { - curl https://api.csswg.org/bikeshed/ -f -F file=@index.bs > index.html; -} - -# Pull requests and commits to other branches shouldn't try to deploy, just build to verify -if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then - echo "Skipping deploy; just doing a build." - doCompile - exit 0 -fi - -# Save some useful information -REPO=`git config remote.origin.url` -SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:} -SHA=`git rev-parse --verify HEAD` - -# Clone the existing gh-pages for this repo into out/ -# Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deply) -git clone $REPO out -cd out -git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH -cd .. - -# Clean out existing contents -rm -rf out/**/* || exit 0 - -# Run our compile script -doCompile - -# Now let's go have some fun with the cloned repo -cd out -git config user.name "Travis CI" -git config user.email "$COMMIT_AUTHOR_EMAIL" - -# If there are no changes to the compiled out (e.g. this is a README update) then just bail. -if [ -z `git diff --exit-code` ]; then - echo "No changes to the output on this push; exiting." - exit 0 -fi - -# Commit the "changes", i.e. the new version. -# The delta will show diffs between new and old versions. -git add . -git commit -m "Deploy to GitHub Pages: ${SHA}" - -# Get the deploy key by using Travis's stored variables to decrypt deploy_key.enc -ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key" -ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv" -ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR} -ENCRYPTED_IV=${!ENCRYPTED_IV_VAR} -openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in deploy_key.enc -out deploy_key -d -chmod 600 deploy_key -eval `ssh-agent -s` -ssh-add deploy_key - -# Now that we're all set up, we can push. -git push $SSH_REPO $TARGET_BRANCH diff --git a/deploy_key.enc b/deploy_key.enc deleted file mode 100644 index 72f382850da84d90b8e935c876837cf925137aec..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3248 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 +Title: Permissions +Repository: w3c/permissions +Status: ED +ED: https://w3c.github.io/permissions/ +TR: https://www.w3.org/TR/permissions/ +Shortname: permissions +Level: 1 +Group: webappsec +Editor: Mounir Lamouri, Google Inc. https://google.com/ +Editor: Marcos Cáceres, Mozilla https://mozilla.com/ +Editor: Jeffrey Yasskin, Google Inc. https://google.com/ + +Abstract: The Permissions Standard defines common infrastructure for other specifications that need to interact with browser permissions. It also defines an API to allow web applications to query and request changes to the status of a given permission. +Mailing List: public-webappsec@w3.org +Mailing List Archives: http://lists.w3.org/Archives/Public/public-webappsec/ + +!Participate: We are on Github. +!Participate: File a bug. +!Participate: Commit history. +!Implementation status: Blink/Chromium +!Implementation status: Gecko + +Markup Shorthands: css no, markdown yes + +
+spec: ECMAScript; urlPrefix: https://tc39.github.io/ecma262/#
+    type: interface
+        text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
+spec: html; urlPrefix: https://html.spec.whatwg.org/multipage/
+    type: dfn
+        text: origin; url: browsers.html#origin-2
+spec: promises-guide; urlPrefix: https://www.w3.org/2001/tag/doc/promises-guide#
+    type: dfn
+        text: Transforming; url: transforming-by
+        text: Promise-calling; url: promise-calling
+
+
+spec: html
+    type: dfn
+        text: browsing context
+        text: environment settings object
+        text: event handler
+        text: event handler event type
+        text: origin
+        text: parent browsing context
+        text: queue a task
+        text: top-level browsing context
+spec: ui-events
+    type: dfn
+        text: user agent
+spec: webidl
+    type: interface
+        text: Promise
+
+ +
+

+ Scope of this document +

+

This section is non-normative.

+

+ This document's goal is to specify an API that will help developers to + handle permissions on the Web platform. Web APIs have different ways to + deal with permissions. The [[notifications]] API allows developers to + request a permission and check the permission status explicitly. Others + might only expose the status to web pages when they try to use the API, + like the [[geolocation-API]] which fails if the permission was not + granted without allowing the developer to check beforehand. +

+

+ Being able to know whether an API call is going to prompt is useful in + order to provide a good user experience. Unfortunately, more often than + not, those prompts can't be controlled by developers. +

+

+ The API specified in this document is meant to provide the tools so + that web applications can improve their user experience when + permissions are involved. +

+

+ The solution described in this document is meant to be extensible but + isn't meant to be applicable to all the current and future permissions + available in the web platform. If you are working on a specification + that has a permission model that wouldn't fit in the model described in + this document, please contact the editors or file an issue. We would + love to hear about it. +

+
+
+

+ Privacy considerations +

+

This section is non-normative.

+

+ Permission states can be used as an element of fingerprinting by + websites. Usually websites could already have access to the information + but often through actually using the API which could lead to a + permission request UI if the permission was not already granted. Thus, + even though this API doesn't expose new fingerprinting data to + websites, it makes it easier for them to have discreet access to it. + Therefore, implementations are encouraged to have an option for users + to block (globally or selectively) the querying of permission states. +

+
+
+

+ Permission descriptor +

+ 
+    dictionary PermissionDescriptor {
+      required PermissionName name;
+    };
+
+

+ A permission is described by a name and other properties that depend on the + name. The simplest permissions require only a name, but some others have + more detailed structure that requires more information to describe it. In + that case, they should define a customized permission descriptor + type dictionary that inherits from {{PermissionDescriptor}}. +

+
+
+

+ Permission Registry +

+ 
+    enum PermissionName {
+      "geolocation",
+      "notifications",
+      "push",
+      "midi",
+      "camera",
+      "microphone",
+      "speaker",
+      "device-info",
+      "background-sync",
+      "bluetooth",
+    };
+
+

+ Each enumeration value in the {{PermissionName}} enum identifies a + permission, which consists of the following + algorithms and types: +

+
+
+ A permission descriptor type +
+
+ {{PermissionDescriptor}} or one of its subtypes. + If unspecified, this defaults to {{PermissionDescriptor}}. +
+
+ A permission storage type +
+
+ {{PermissionStorage}} or one of its subtypes. + If unspecified, this defaults to {{PermissionStorage}}. +
+
+ A permission result type +
+
+ {{PermissionStatus}} or one of its subtypes. + If unspecified, this defaults to {{PermissionStatus}}. +
+
+ A permission query algorithm +
+
+ Takes an instance of the permission descriptor type, + an instance of the permission storage type that's currently + stored for this permission, and a new or existing instance of + the permission result type, and updates the permission + result type instance with the query result. Used by + {{Permissions}}' {{Permissions/query()}} + method and the PermissionStatus + update steps. If unspecified, this defaults to the boolean + permission query algorithm. +
+
+ A permission request algorithm +
+
+ Takes the previously-stored instance of the permission storage + type, an instance of the permission descriptor type, + and a newly-created instance of the permission result type. + Shows the user any necessary prompt to try to increase permissions, + and updates the instances of the permission storage type and + permission result type to match. May return a {{Promise}} + if the request can fail exceptionally. (Merely being denied + permission is not exceptional.) Used by {{Permissions}}' + {{Permissions/request()}} method, which handles + reading and writing the permission store. If unspecified, this + defaults to the boolean permission request algorithm. +
+
+ A permission revocation algorithm +
+
+ Takes no arguments. Updates any other parts of the implementation + that need to be kept in sync after an entry is removed from the + permission store. Triggered by {{Permissions}}' + {{Permissions/revoke()}} method. If unspecified, this + defaults to doing nothing. +
+
+

+ A boolean permission is a permission with all types + and algorithms defaulted. +

+
+

+ Geolocation +

+

+ The "geolocation" + permission is the permission associated with the usage of the + [[geolocation-API]]. It is a boolean permission. +

+
+
+

+ Notifications +

+

+ The "notifications" + permission is the permission associated with the usage of the + [[notifications]] API. It is a boolean permission. +

+
+
+

+ Push +

+

+ The "push" + permission is the permission associated with the usage of the + [[push-api]]. +

+
+
+ permission descriptor type +
+
+ 
+          dictionary PushPermissionDescriptor : PermissionDescriptor {
+            boolean userVisibleOnly = false;
+          };
+
+
+
+
+
+

+ Midi +

+

+ The "midi" + permission is the permission associated with the usage of + [[webmidi]]. +

+
+
+ permission descriptor type +
+
+ 
+          dictionary MidiPermissionDescriptor : PermissionDescriptor {
+            boolean sysex = false;
+          };
+
+
+
+
+
+

+ Media Devices +

+

+ The "camera", "microphone" , and + "speaker" + permissions are associated with permission to use media devices as + specified in [[GETUSERMEDIA]] and [[audio-output]]. +

+
+
+ permission descriptor type +
+
+ 
+          dictionary DevicePermissionDescriptor : PermissionDescriptor {
+            DOMString deviceId;
+          };
+
+

+ A permission covers access to the device given in the associated + descriptor. +

+

+ If the descriptor does not have a {{deviceId}}, its semantic is that + it queries for access to all devices of that class. Thus, if a + query for the {{"camera"}} permission with no {{deviceId}} returns + {{"granted"}}, the client knows that there will never be a permission + prompt for a camera, and if {{"denied"}} is returned, it knows that + no getUserMedia request for a camera will succeed. +

+

+ If a permission state is present for access to some, but not all, + cameras, a query without the {{deviceId}} will return {{"prompt"}}. +

+
+
+ permission storage type +
+
+ TODO +
+
+ permission result type +
+
+ TODO +
+
+ permission query algorithm +
+
+ TODO +
+
+ permission request algorithm +
+
+ TODO +
+
+ permission revocation algorithm +
+
+ TODO: Stop playing/recording data? +
+
+

+ The "device-info" + permission controls access to names and capabilities of input and + output devices. +

+

+ A successful call to the getUserMedia function of + [[GETUSERMEDIA]] MUST cause permission to be granted for the returned + devices, and MAY cause other permissions to be granted. +

+

+ Stopping a MediaStreamTrack MAY cause permission to be revoked for + the associated device. +

+
+
+

+ Background Sync +

+

+ The "background-sync" + permission is the permission associated with the usage of + [[web-background-sync]]. +

+
+
+
+

+ Permission Store +

+

+ User agents MAY use a form of storage to + keep track of web site permissions. When they do, they MUST have a + permission storage identifier which is linked to a + {{PermissionStorage}} instance or one of its subtypes. +

+

+ To get a permission storage identifier for a + {{PermissionName}} name and an environment settings + object settings, the UA MUST return a tuple consisting + of: +

+
    +
  1. + name +
    2. +
  2. + settings' origin +
    3. +
  3. optional UA-specific data like whether settings' + browsing context has a parent browsing context, or + settings' top-level browsing context's origin +
    4. +
+ 
+    dictionary PermissionStorage {
+      // PermissionStorage is just an explanatory device.
+      // Instances are never received from or passed to Javascript code.
+
+      required PermissionState state;
+    };
+
+

+ The steps to retrieve a permission storage entry of a + permission storage identifier are as follows: +

+
    +
  1. If the user agent has a {{PermissionStorage}} associated + with the permission storage identifier in its permission store, + it MUST return the {{PermissionStorage}}. +
    2. +
  2. Otherwise, it MUST return undefined. +
    3. +
+

+ The steps to create a permission storage entry for a + permission storage identifier are as follows: +

+
    +
  1. If the user agent has a {{PermissionStorage}} associated + with the permission storage identifier in its permission store, + it MUST overwrite it to the given {{PermissionStorage}}. +
    2. +
  2. Otherwise, it MUST write the new {{PermissionStorage}} to its + permission store. +
    3. +
+

+ The steps to delete a permission storage entry of a + permission storage identifier are as follows: +

+
    +
  1. If the user agent has a {{PermissionStorage}} associated + with the permission storage identifier in its permission store, + it MUST remove it. +
    2. +
+
+
+

+ Status of a permission +

+ 
+    enum PermissionState {
+      "granted",
+      "denied",
+      "prompt",
+    };
+
+

+ The "granted" state represents + that the caller will be able + to successfuly access the feature without having the user agent + asking the user's permission. +

+

+ The "denied" state represents + that the caller will not be + able to access the feature. +

+

+ The "prompt" state represents + that the user agent + will be asking the user's permission if the caller tries to access the + feature. The user might grant, deny or dismiss the request. +

+

+ The steps to retrieve the permission storage for a given + {{PermissionName}} name are as follows: +

+
    +
  1. + Get a permission storage identifier for name and + the current environment settings object, and let + identifier be the result. +
    2. +
  2. Run the steps to retrieve a permission storage entry of + identifier. +
    3. +
  3. If the result of those steps are not undefined, return + it and abort these steps. +
    4. +
  4. Otherwise, the user agent MUST return a default value based + on user agent's defined heuristics. For example, {state: + {{"prompt"}}} can be a default value, but it can also be based on + frequency of visits. +
    5. +
+ 
+    [Exposed=(Window,Worker)]
+    interface PermissionStatus : EventTarget {
+      readonly attribute PermissionState state;
+      attribute EventHandler onchange;
+    };
+
+

+ {{PermissionStatus}} instances are created with the following + internal slots: +

+
+
+ \[[permission]] +
+
+ A permission. {{[[permission]]}} is always the + permission named {{[[query]]}}.{{PermissionDescriptor/name}}. +
+
+ \[[query]] +
+
+ A {{PermissionDescriptor}}. +
+
+

+ The steps to update the state of a + {{PermissionStatus}} instance status are as + follows: +

+
    +
  1. Run the steps to retrieve the permission storage for + status@{{[[query]]}}.{{PermissionDescriptor/name}}, + and let storage be the result. +
    2. +
  2. Run status@{{[[permission]]}}'s permission + query algorithm, passing status@{{[[query]]}}, + storage, and status. +
    3. +
+

+ The steps to create a PermissionStatus for a given + {{PermissionDescriptor}} permissionDesc are as follow: +

+
    +
  1. Let permission be the permission named by + permissionDesc.name. +
    2. +
  2. Let status be a new instance of permission's + permission result type, with the internal slots filled as: + + + + + + + + + + + + + + + +
    + Slot + + Value +
    + {{PermissionStatus/[[permission]]}} + + permission +
    + {{PermissionStatus/[[query]]}} + + permissionDesc +
    +
    3. +
  3. Return status. +
    4. +
+

+ The state + attribute MUST return the latest value that was set on the current + instance. +

+

+ The onchange attribute is an + event handler whose corresponding event handler event + type is change. +

+

+ Whenever the user agent is aware that the state of a + {{PermissionStatus}} instance status has changed, + it MUST asynchronously run the following steps: +

+
    +
  1. Run the steps to update the state of status. +
    2. +
  2. + Queue a task on the permission task source to + fire an event named change at + status. +
    3. +
+
+
+ +

+ A {{Permissions}} instance is exposed on the navigator + object for {{Window}} and {{Worker}} contexts. +

+ 
+    [Exposed=(Window)]
+    partial interface Navigator {
+      readonly attribute Permissions permissions;
+    };
+
+ 
+    [Exposed=(Worker)]
+    partial interface WorkerNavigator {
+      readonly attribute Permissions permissions;
+    };
+
+
+
+

+ Permissions interface +

+ 
+    [Exposed=(Window,Worker)]
+    interface Permissions {
+      Promise<PermissionStatus> query(PermissionDescriptor permissionDesc);
+
+      Promise<PermissionStatus> request(PermissionDescriptor permissionDesc);
+
+      Promise<PermissionStatus> revoke(PermissionDescriptor permissionDesc);
+    };
+
+

+ When the query() method is invoked, + the user agent MUST run the following query a + permission algorithm, passing the parameter + permissionDesc: +

+
    +
  1. If permissionDesc.name has a permission + descriptor type other than {{PermissionDescriptor}}, convert the + underlying ECMAScript object to the permission descriptor type + dictionary as + described in + [[!WEBIDL]], then: +
      +
    • If that operation failed, return a {{Promise}} rejected with + a {{TypeError}} and abort these steps. +
      • +
    • Otherwise, set permissionDesc to the result of the + operation. +
      • +
    +
    2. +
  2. Let promise be a newly-created {{Promise}}. +
    3. +
  3. Return promise and continue the following steps + asynchronously. +
    4. +
  4. Run the steps to create a PermissionStatus for + permissionDesc, and let status be the result. +
    5. +
  5. Run the steps to update the state on status. +
    6. +
  6. Resolve promise with status. +
    7. +
+
+ If a developer wants to check multiple permissions at once, the editors + recommend the use of {{Promise}}.all(). An example can be + found in the Examples section. +
+

+ When the request() method is invoked, + the user agent MUST run the following request a + permission algorithm, passing the parameter + permissionDesc: +

+
    +
  1. If permissionDesc.name has a permission + descriptor type other than {{PermissionDescriptor}}, convert the + underlying ECMAScript object to the permission descriptor type + dictionary as + described in + [[!WEBIDL]], then: +
      +
    • If that operation failed, return a {{Promise}} rejected with + a {{TypeError}} and abort these steps. +
      • +
    • Otherwise, set permissionDesc to the result of the + operation. +
      • +
    +
    2. +
  2. Let promise be a newly-created {{Promise}}. +
    3. +
  3. Return promise and continue the following steps + asynchronously. +
    4. +
  4. Let permission be the permission named by + permissionDesc.name. +
    5. +
  5. Run the steps to create a PermissionStatus for + permissionDesc, and let status be the result. +
    6. +
  6. Run the steps to retrieve the permission storage for + permission, and let storage be the result. +
    7. +
  7. Let result be the result of promise-calling + permission's permission request algorithm with + storage, permissionDesc, and status + as arguments. +
    8. +
  8. Resolve promise with the result of transforming + result with a fulfillment handler that runs the following + steps. +
    9. +
  9. + Get a permission storage identifier for + permissionDesc.name and the current + environment settings object, and create a permission + storage entry mapping this identifier to storage. +
    10. +
  10. Return status. +
    11. +
+

+ When the revoke() + method is invoked, the user agent MUST run the following + revoke a permission algorithm, passing the + parameter permissionDesc: +

+
    +
  1. If permissionDesc.name has a permission + descriptor type other than {{PermissionDescriptor}}, convert the + underlying ECMAScript object to the permission descriptor type + dictionary as + described in + [[!WEBIDL]], then: +
      +
    • If that operation failed, return a {{Promise}} rejected with + a {{TypeError}} and abort these steps. +
      • +
    • Otherwise, set permissionDesc to the result of the + operation. +
      • +
    +
    2. +
  2. Let promise be a newly-created {{Promise}}. +
    3. +
  3. Return promise and continue the following steps + asynchronously. +
    4. +
  4. + Get a permission storage identifier for + permission.name and the current + environment settings object, and let identifier be + the result. +
    5. +
  5. Run the steps to delete a permission storage entry using + identifier. +
    6. +
  6. Run permissionDesc.name's permission revocation + algorithm. +
    7. +
  7. Run the steps to create a PermissionStatus for + permissionDesc, and let status be the result. +
    8. +
  8. Run the steps to update the state on status. +
    9. +
  9. Resolve promise with status. +
    10. +
+
+
+

+ Common permission algorithms +

+

+ The boolean permission query algorithm, given a + {{PermissionDescriptor}} permissionDesc, a + {{PermissionStorage}} storage, and a + {{PermissionStatus}} status, runs the following steps: +

+
    +
  1. Set status.state to + storage.state +
    2. +
+

+ The boolean permission request algorithm, given a + {{PermissionDescriptor}} permission and a + {{PermissionStatus}} status, runs the following steps: +

+
    +
  1. TODO +
    2. +
+
+
+

+ Examples +

+
+

+ This example uses the Permissions API to decide whether local news + should be shown using the Geolocation API or with a button offering to + add the feature. +

+ 
+    <script>
+      navigator.permissions.query({name:'geolocation'}).then(function(result) {
+        if (result.state == 'granted') {
+          showLocalNewsWithGeolocation();
+        } else if (result.state == 'prompt') {
+          showButtonToEnableLocalNews();
+        }
+        // Don't do anything if the permission was denied.
+      });
+    </script>
+
+
+
+

+ This example is using the {{"notifications"}} permission for a + chat application to show a notification button depending on the + permission state. +

+ 
+    <script>
+      function updateNotificationButton(state) {
+        document.getElementById('chat-notification-button').disabled = (state == 'denied');
+      }
+
+      navigator.permissions.query({name:'notifications'}).then(function(result) {
+        updateNotificationButton(result.state);
+
+        result.addEventListener('change', function() {
+          updateNotificationButton(this.state);
+        });
+      });
+    </script>
+
+
+
+

+ This example is checking whether the page has the + {{"geolocation"}} and the {{"notifications"}} permissions + using {{Promise}}.all. +

+ 
+    <script>
+      Promise.all([navigator.permissions.query({name:'geolocation'}),
+                   navigator.permissions.query({name:'notifications'})])
+      .then(function(result) {
+        console.log('Geolocation permission state is ' + result[0].state);
+        console.log('Notifications permission state is ' + result[1].state);
+      });
+    </script>
+
+
+
+

+ This example is checking whether the page has the {{"camera"}} + permission for the first device in the list. Error checking omitted. +

+ 
+    <script>
+      navigator.mediaDevices.enumerateDevices()
+      .then(function(devices) {
+         return navigator.permissions.query({name:'camera',
+                                             deviceId: devices[0].deviceId})
+      })
+      .then(function(result) {
+         console.log('Camera permission to first camera is ' + result.state);
+      }
+      .catch(err => console.log('Bad things happened: ' + err.name));
+    </script>
+
+
+
+
+

+ Acknowledgments +

+

+ The editors would like to thank Adrienne Porter Felt, Anne van + Kesteren, Domenic Denicola, Jake Archibald and Wendy Seltzer for their + help with the API design and editorial work. +

+
diff --git a/published/FPWD.html b/published/FPWD.html new file mode 100644 index 0000000..2966fa0 --- /dev/null +++ b/published/FPWD.html @@ -0,0 +1,1071 @@ + + + + + The Permissions API + + + + + + +

Abstract

+ The Permissions API allows a web application to be aware of + the status of a given permission, to know whether it is granted, denied + or if the user will be asked whether the permission should be granted. +

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

+ This document was published by the Web Application Security Working Group as a First Public Working Draft. + + This document is intended to become a W3C Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-webappsec@w3.org + (subscribe, + archives). + + + + + + + All comments are welcome. + + +

+ + + +

+ Publication as a First Public Working Draft does not imply endorsement by the W3C + Membership. This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other than work in + progress. +

+ + + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ +

This document is governed by the 1 August 2014 W3C Process Document. +

+ + + + + +

Table of Contents

+ +

1. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

The key words MAY, MUST, and RECOMMENDED are + to be interpreted as described in [RFC2119]. +

+ +

+ This specification defines conformance criteria that apply to a single + product: the user agent that implements the interfaces that + it contains. +

+

+ Implementations that use ECMAScript to expose the APIs defined in this + specification MUST implement them in a manner consistent with the + ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. +

+
+
+

2. + Dependencies +

+

+ The following concepts and interfaces are defined in [HTML]: +

+ +

+ + Promise objects are defined in [ECMASCRIPT]. +

+
+
+

3. + Scope of this document +

This section is non-normative.

+

+ This document goal is to specify an API that will help developers to + handle permissions on the Web platform. Web APIs have different ways to + deal with permissions. The [notifications] API allows developers to + request a permission and check the permission status explicitly. Others + might only expose the status to web pages. Some, like [geolocation-API] + will keep the page unaware of the permission associated with the + feature. +

+

+ Being able to know whether an API call is going to prompt is mandatory + in order to provide a good user experience. Unfortunately, more often + than not, those prompts can't be controlled by the developers. +

+

+ The API specified in this document is meant to provide the tools so + that web applications can improve their user experience when + permissions are involved. +

+

+ The solution described in this document is meant to be extensible but + isn't meant to be applicable to all the current and future permissions + available in the web platform. If you are working on a specification + that has a permission model that wouldn't fit in the model described in + this document, please contact the editors or file an issue. We would + love to hear about it. +

+

+ The initial intent of this document was to allow web applications to + request and revoke permissions explicitly in addition of query the + permission status. This is an aspect of the specification that was + controversial thus removed from the current document in a spirit of + incremental changes: settling on a small API that can be improved. +

+
+
+

4. + Permission Registry +

+ 
enum PermissionName {
+    "geolocation",
+    "notifications",
+    "push-notifications",
+    "midi-sysex"
+};
+

+ The PermissionName enum defines the list of known + permissions. These permissions are meant to be associated with a use + case instead of one API. Thus, some permissions have a 1:1 relationship + with an API while some others might include more than one API or even a + subset of an API. +

+
Note

+ For example, push-notifications is exposing the ability for a + web page to use push messages in order to show notifications. + Implementations might associate it with full usage of the Push API and + the Notifications API while others will force the callers to use the + Push API only in order to use the Notifications API. +

+

+ Specifications are welcome to request a new name to be added to this + registry instead of trying to monkey patch it. +

+

+ The geolocation + permission is the permission associated with the usage of the + [geolocation-API]. +

+

+ The notifications + permission is the permission associated with the usage of the + [notifications] API. +

+

+ The push-notifications + permission is the permission associated with the usage of the + [push-api] in order to show notifications using the [notifications] + API. +

+

+ The midi-sysex permission + is the permission associated with the usage of sysex messages in the + [webmidi] API. +

+
+
+

5. + Permission definition +

+ 
dictionary Permission {
+    required PermissionName name;
+};
+

+ A Permission dictionary MUST contain a name field which represents the + permission's identifier. +

+

+ If a permission has to be defined by more than its name, it is + RECOMMENDED to inherit from Permission dictionary and add + new fields. +

+
Note
+ There are currently no permission defined in this specification using + this dictionary. It is only specified here in order to expose the + ability for the API to be extended to more complex permissions.
+ For example, if the [quota-api] were to have an associated + permission, it could define a QuotaPermission dictionary extending + Permission with type and value fields. +
+
+
+

6. + Status of a permission +

+ 
enum PermissionState {
+    "granted",
+    "denied",
+    "prompt"
+};
+

+ The steps to retrieve the permission state of a global + object for a given permission are as follows: +

+
    +
  1. If the user agent will allow the global object to try + to access the features associated with the permission but + will prompt the user to know whether the call should succeed or fail, + the user agent MUST return prompt. +
    2. +
  2. Otherwise, if the user agent will allow the global + object to access the features associated with the + permission without prompting the user, the user + agent MUST return granted . +
    3. +
  3. Otherwise, the user agent will not allow the global + object to access the feature associated with + permission and MUST return denied . +
    4. +
+

+ How the user agent decides whether a global object is + allowed or not to access some features is left as an implementation + details. However, the implementation MUST be consistent and not return + different values unless something happened (user action, expiration). +

+

+ It is RECOMMENDED for implementations to use the origins of the Document or Worker when + making security decisions. Other factors MAY also apply like whether + the permission is associated with a [powerful-features] or whether + the Document is embedded. +

+
Issue 1
+ The retrieve the permission state algorithm does not take into + account all the theoretically possible use cases. It tries to stay + inside the scope of the permissions described in this document.
+ There are open questions about use cases where it might not work as + well: issue 8 + and issue 9. +
+ 
[Exposed=(Window,Worker)]
+interface PermissionStatus : EventTarget {
+    readonly    attribute Permission      permission;
+    readonly    attribute PermissionState status;
+                attribute EventHandler    onchange;
+};
+

+ The steps to update the status of a + PermissionStatus instance are as follow: +

+
    +
  1. Let status be the PermissionStatus instance + being updated. +
    2. +
  2. Run the steps to retrieve the permission state using the + status' global object and permission + attribute then set the result of those steps to the status + attribute. +
    3. +
+

+ The steps to create a PermissionStatus for a given + permission are as follow: +

+
    +
  1. Let status be a PermissionStatus instance. +
    2. +
  2. Set the permission attribute to + permission. +
    3. +
  3. Run the steps to update the status on status. +
    4. +
  4. Return status. +
    5. +
+

+ The permission attribute + MUST return the Permission it was initially set to + at the object creation. +

+

+ The status + attribute MUST return the latest value that was set while running the + update the status steps on the current instance. +

+

+ The onchange attribute is an + event handler whose corresponding event handler event + type is change. +

+

+ Whenever the user agent is aware that the status of + a PermissionStatus instance has changed, it MUST + asynchronously run the following steps: +

+
    +
  1. Let permission-status be the + PermissionStatus for which the status has + changed. +
    2. +
  2. Run the steps to update the status of + permission-status. +
    3. +
  3. + Queue a task on the permission task source to + fire a simple event named change at + permission-status. +
    4. +
+
+
+

7. + Permissions interface +

+ 
[Exposed=(Window,Worker)]
+interface Permissions {
+    static Promise<PermissionStatus> query ((Permission or PermissionName) permission);
+};
+

+ When the + query() method is invoked, the user agent MUST run + the following steps: +

+
    +
  1. Let permission be permission argument if + permission is of type Permission, otherwise, + create a Permission instead for which name is + set to the permission argument value. +
    2. +
  2. Let promise be a newly-created Promise. +
    3. +
  3. Return promise and continue those steps asynchronously. +
    4. +
  4. Run the steps to create a PermissionStatus using the + global object and permission and resolve + promise with the result of those steps. +
    5. +
+
Note
+ If a developer wants to check multiple permissions at once, the editors + recommend them to use Promises.all(). It should yield to the same + result and allow this API to stay simple. If it happens to be a very + common use case, it should be easy to extend Permissions.query() to + accept a sequence<> too. +
+
+
+

8. + Examples +

This section is non-normative.

+

+ This example uses the Permissions API to decide whether local news + should be shown using the Geolocation API or a button offering that + feature should be added. +

+
Example 1
<script>
+  Permissions.query('geolocation').then(function(result) {
+    if (result.status == 'granted') {
+      showLocalNewsWithGeolocation();
+    } else if (result.status == 'prompt') {
+      showButtonToEnableLocalNews();
+    }
+    // Don't do anything if the permission was denied.
+  });
+</script>
+

+ This example is using the notifications permission for a + chat application to show a notification button depending on the + permission status. +

+
Example 2
<script>
+  function updateNotificationButton(permission) {
+    document.getElementById('chat-notification-button').disabled = (permission.status == 'denied');
+  }
+
+  Permissions.query('notifications').then(function(result) {
+    updateNotificationButton(result);
+
+    result.addEventListener('change', function() {
+      updateNotificationButton(this);
+    });
+  });
+</script>
+
+ +
+

A. + Acknowledgments +

+

+ Thanks to Adrienne Porter Felt and Jake Archibald for their early + support and help. +

+
+ + +

B. References

B.1 Normative references

[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification, Edition 6. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html +
[HTML]
Ian Hickson. HTML. Living Standard. URL: https://html.spec.whatwg.org/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 +
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/ +

B.2 Informative references

[geolocation-API]
Andrei Popescu. Geolocation API Specification. 24 October 2013. W3C Recommendation. URL: http://www.w3.org/TR/geolocation-API/ +
[notifications]
John Gregg; Anne van Kesteren. Web Notifications. 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/notifications/ +
[powerful-features]
Mike West. Requirements for Powerful Features. 4 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/powerful-features/ +
[push-api]
Bryan Sullivan; Eduardo Fullea; Michael van Ouwerkerk. Push API. 7 October 2014. W3C Working Draft. URL: http://www.w3.org/TR/push-api/ +
[quota-api]
Kinuko Yasuda. Quota Management API. 5 November 2013. W3C Working Draft. URL: http://www.w3.org/TR/quota-api/ +
[webmidi]
Chris Wilson; Jussi Kalliokoski. Web MIDI API. 17 March 2015. W3C Working Draft. URL: http://www.w3.org/TR/webmidi/ +
From 914a40f03cfb5a79013ad09cb0684e4d45f67a65 Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 22:43:19 +0100 Subject: [PATCH 03/11] Add automatic deployment from 'master' to 'gh-pages'. Using @domenic's guide: https://gist.github.com/domenic/ec8b0fc8ab45f39403dd --- .gitignore | 1 + .travis.yml | 8 + deploy.sh | 63 ++ deploy_key.enc | Bin 0 -> 3248 bytes index.html | 2353 ------------------------------------------- published/FPWD.html | 1071 -------------------- 6 files changed, 72 insertions(+), 3424 deletions(-) create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 deploy.sh create mode 100644 deploy_key.enc delete mode 100644 index.html delete mode 100644 published/FPWD.html diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8f00ed6 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +deploy_key diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..42f58a4 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +language: generic + +script: bash ./deploy.sh + +env: + global: + - ENCRYPTION_LABEL: 104fbe69e8fa + - COMMIT_AUTHOR_EMAIL: travis-ci@w3.org diff --git a/deploy.sh b/deploy.sh new file mode 100644 index 0000000..be8e31e --- /dev/null +++ b/deploy.sh @@ -0,0 +1,63 @@ +#!/bin/bash +set -e # Exit with nonzero exit code if anything fails + +SOURCE_BRANCH="master" +TARGET_BRANCH="gh-pages" + +function doCompile { + curl https://api.csswg.org/bikeshed/ -f -F file=@index.bs > index.html; +} + +# Pull requests and commits to other branches shouldn't try to deploy, just build to verify +if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then + echo "Skipping deploy; just doing a build." + doCompile + exit 0 +fi + +# Save some useful information +REPO=`git config remote.origin.url` +SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:} +SHA=`git rev-parse --verify HEAD` + +# Clone the existing gh-pages for this repo into out/ +# Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deply) +git clone $REPO out +cd out +git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH +cd .. + +# Clean out existing contents +rm -rf out/**/* || exit 0 + +# Run our compile script +doCompile + +# Now let's go have some fun with the cloned repo +cd out +git config user.name "Travis CI" +git config user.email "$COMMIT_AUTHOR_EMAIL" + +# If there are no changes to the compiled out (e.g. this is a README update) then just bail. +if [ -z `git diff --exit-code` ]; then + echo "No changes to the output on this push; exiting." + exit 0 +fi + +# Commit the "changes", i.e. the new version. +# The delta will show diffs between new and old versions. +git add . +git commit -m "Deploy to GitHub Pages: ${SHA}" + +# Get the deploy key by using Travis's stored variables to decrypt deploy_key.enc +ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key" +ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv" +ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR} +ENCRYPTED_IV=${!ENCRYPTED_IV_VAR} +openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in deploy_key.enc -out deploy_key -d +chmod 600 deploy_key +eval `ssh-agent -s` +ssh-add deploy_key + +# Now that we're all set up, we can push. +git push $SSH_REPO $TARGET_BRANCH diff --git a/deploy_key.enc b/deploy_key.enc new file mode 100644 index 0000000000000000000000000000000000000000..72f382850da84d90b8e935c876837cf925137aec GIT binary patch literal 3248 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 - - - - Permissions - - - - -
-

-

Permissions

-

Editor’s Draft,

-
-
-
This version: -
https://w3c.github.io/permissions/ -
Latest version: -
https://www.w3.org/TR/permissions/ -
Feedback: -
public-webappsec@w3.org with subject line “[permissions] … message topic …” -
Issue Tracking: -
GitHub -
Editors: -
Mounir Lamouri (Google Inc.) -
Marcos Cáceres (Mozilla) -
Jeffrey Yasskin (Google Inc.) -
-
Participate: -
We are on Github. -
File a bug. -
Commit history. -
Implementation status: -
Blink/Chromium -
Gecko -
-
-
-
-

Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.

-
-
-

Abstract

-
-

The Permissions Standard defines common infrastructure for other specifications that need to interact with browser permissions. It also defines an API to allow web applications to query and request changes to the status of a given permission.

-
-

Status of this document

-
-

This is a public copy of the editors’ draft. - It is provided for discussion only and may change at any moment. - Its publication here does not imply endorsement of its contents by W3C. - Don’t cite this document other than as work in progress.

-

Changes to this document may be tracked at https://github.com/w3c/webappsec.

-

The (archived) public mailing list public-webappsec@w3.org (see instructions) - is preferred for discussion of this specification. - When sending e-mail, - please put the text “permissions” in the subject, - preferably like this: - “[permissions] …summary of comment…”

-

This document was produced by the Web Application Security Working Group.

-

This document was produced by a group operating under - the 5 February 2004 W3C Patent Policy. - W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; - that page also includes instructions for disclosing a patent. - An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

-

This document is governed by the 1 September 2015 W3C Process Document.

-

-
-
- -
-
-

1. Scope of this document

-

This section is non-normative.

-

This document’s goal is to specify an API that will help developers to - handle permissions on the Web platform. Web APIs have different ways to - deal with permissions. The [notifications] API allows developers to - request a permission and check the permission status explicitly. Others - might only expose the status to web pages when they try to use the API, - like the [geolocation-API] which fails if the permission was not - granted without allowing the developer to check beforehand.

-

Being able to know whether an API call is going to prompt is useful in - order to provide a good user experience. Unfortunately, more often than - not, those prompts can’t be controlled by developers.

-

The API specified in this document is meant to provide the tools so - that web applications can improve their user experience when - permissions are involved.

-

The solution described in this document is meant to be extensible but - isn’t meant to be applicable to all the current and future permissions - available in the web platform. If you are working on a specification - that has a permission model that wouldn’t fit in the model described in - this document, please contact the editors or file an issue. We would - love to hear about it.

-
-
-

2. Privacy considerations

-

This section is non-normative.

-

Permission states can be used as an element of fingerprinting by - websites. Usually websites could already have access to the information - but often through actually using the API which could lead to a - permission request UI if the permission was not already granted. Thus, - even though this API doesn’t expose new fingerprinting data to - websites, it makes it easier for them to have discreet access to it. - Therefore, implementations are encouraged to have an option for users - to block (globally or selectively) the querying of permission states.

-
-
-

3. Permission descriptor

-
dictionary PermissionDescriptor#dictdef-permissiondescriptorReferenced in:3. 
-    Permission descriptor
-  4. 
-    Permission Registry
-   (2)4.3. 
-      Push
-    4.4. 
-      Midi
-    4.5. 
-      Media Devices
-    6. 
-    Status of a permission
-   (2)8. 
-    Permissions interface
-   (2) (3) (4) (5) (6)9. 
-    Common permission algorithms
-   (2) {
-  required PermissionName name#dom-permissiondescriptor-nameReferenced in:6. 
-    Status of a permission
-   (2);
-};
-
-

A permission is described by a name and other properties that depend on the - name. The simplest permissions require only a name, but some others have - more detailed structure that requires more information to describe it. In - that case, they should define a customized permission descriptor - type dictionary that inherits from PermissionDescriptor.

-
-
-

4. Permission Registry

-
enum PermissionName#enumdef-permissionnameReferenced in:3. 
-    Permission descriptor
-  4. 
-    Permission Registry
-  5. 
-    Permission Store
-  6. 
-    Status of a permission
-   {
-  "geolocation",
-  "notifications",
-  "push",
-  "midi",
-  "camera",
-  "microphone",
-  "speaker",
-  "device-info",
-  "background-sync",
-  "bluetooth",
-};
-
-

Each enumeration value in the PermissionName enum identifies a permission#permissionReferenced in:4. - Permission Registry (2)6. - Status of a permission (2) (3)8. - Permissions interface , which consists of the following - algorithms and types:

-
-
A permission descriptor type#permission-descriptor-typeReferenced in:3. - Permission descriptor 4. - Permission Registry (2)4.3. - Push 4.4. - Midi 4.5. - Media Devices 8. - Permissions interface (2) (3) (4) (5) (6) -
PermissionDescriptor or one of its subtypes. - If unspecified, this defaults to PermissionDescriptor. -
A permission storage type#permission-storage-typeReferenced in:4. - Permission Registry (2) (3)4.5. - Media Devices -
PermissionStorage or one of its subtypes. - If unspecified, this defaults to PermissionStorage. -
A permission result type#permission-result-typeReferenced in:4. - Permission Registry (2) (3) (4)4.5. - Media Devices 6. - Status of a permission -
PermissionStatus or one of its subtypes. - If unspecified, this defaults to PermissionStatus. -
A permission query algorithm#permission-query-algorithmReferenced in:4.5. - Media Devices 6. - Status of a permission -
Takes an instance of the permission descriptor type, - an instance of the permission storage type that’s currently - stored for this permission, and a new or existing instance of - the permission result type, and updates the permission - result type instance with the query result. Used by Permissions' query() method and the PermissionStatus - update steps. If unspecified, this defaults to the boolean - permission query algorithm. -
A permission request algorithm#permission-request-algorithmReferenced in:4.5. - Media Devices 8. - Permissions interface -
Takes the previously-stored instance of the permission storage - type, an instance of the permission descriptor type, - and a newly-created instance of the permission result type. - Shows the user any necessary prompt to try to increase permissions, - and updates the instances of the permission storage type and permission result type to match. May return a Promise if the request can fail exceptionally. (Merely being denied - permission is not exceptional.) Used by Permissions' request() method, which handles - reading and writing the permission store. If unspecified, this - defaults to the boolean permission request algorithm. -
A permission revocation algorithm#permission-revocation-algorithmReferenced in:4.5. - Media Devices 8. - Permissions interface -
Takes no arguments. Updates any other parts of the implementation - that need to be kept in sync after an entry is removed from the - permission store. Triggered by Permissions' revoke() method. If unspecified, this - defaults to doing nothing. -
-

A boolean permission#boolean-permissionReferenced in:4.1. - Geolocation 4.2. - Notifications is a permission with all types - and algorithms defaulted.

-
-

4.1. Geolocation

-

The "geolocation"#dom-permissionname-geolocationReferenced in:4. - Permission Registry 10. - Examples permission is the permission associated with the usage of the [geolocation-API]. It is a boolean permission.

-
-
-

4.2. Notifications

-

The "notifications"#dom-permissionname-notificationsReferenced in:4. - Permission Registry 10. - Examples (2) permission is the permission associated with the usage of the [notifications] API. It is a boolean permission.

-
-
-

4.3. Push

-

The "push"#dom-permissionname-pushReferenced in:4. - Permission Registry permission is the permission associated with the usage of the [push-api].

-
-
permission descriptor type -
-
dictionary PushPermissionDescriptor : PermissionDescriptor {
-  boolean userVisibleOnly = false;
-};
-
-
-
-
-

4.4. Midi

-

The "midi"#dom-permissionname-midiReferenced in:4. - Permission Registry permission is the permission associated with the usage of [webmidi].

-
-
permission descriptor type -
-
dictionary MidiPermissionDescriptor : PermissionDescriptor {
-  boolean sysex = false;
-};
-
-
-
-
-

4.5. Media Devices

-

The "camera"#dom-permissionname-cameraReferenced in:4. - Permission Registry 4.5. - Media Devices 10. - Examples , "microphone"#dom-permissionname-microphoneReferenced in:4. - Permission Registry , and "speaker"#dom-permissionname-speakerReferenced in:4. - Permission Registry permissions are associated with permission to use media devices as - specified in [GETUSERMEDIA] and [audio-output].

-
-
permission descriptor type -
-
dictionary DevicePermissionDescriptor : PermissionDescriptor {
-  DOMString deviceId#dom-devicepermissiondescriptor-deviceidReferenced in:4.5. 
-      Media Devices
-     (2) (3);
-};
-
-

A permission covers access to the device given in the associated - descriptor.

-

If the descriptor does not have a deviceId, its semantic is that - it queries for access to all devices of that class. Thus, if a - query for the "camera" permission with no deviceId returns "granted", the client knows that there will never be a permission - prompt for a camera, and if "denied" is returned, it knows that - no getUserMedia request for a camera will succeed.

-

If a permission state is present for access to some, but not all, - cameras, a query without the deviceId will return "prompt".

-
permission storage type -
TODO -
permission result type -
TODO -
permission query algorithm -
TODO -
permission request algorithm -
TODO -
permission revocation algorithm -
TODO: Stop playing/recording data? -
-

The "device-info"#dom-permissionname-device-infoReferenced in:4. - Permission Registry permission controls access to names and capabilities of input and - output devices.

-

A successful call to the getUserMedia function of [GETUSERMEDIA] MUST cause permission to be granted for the returned - devices, and MAY cause other permissions to be granted.

-

Stopping a MediaStreamTrack MAY cause permission to be revoked for - the associated device.

-
-
-

4.6. Background Sync

-

The "background-sync"#dom-permissionname-background-syncReferenced in:4. - Permission Registry permission is the permission associated with the usage of [web-background-sync].

-
-
-
-

5. Permission Store #permission-storeReferenced in:4. - Permission Registry

-

User agents MAY use a form of storage to - keep track of web site permissions. When they do, they MUST have a permission storage identifier#permission-storage-identifierReferenced in:5. - Permission Store (2) (3) (4) (5) (6) which is linked to a PermissionStorage instance or one of its subtypes.

-

To get a permission storage identifier#get-a-permission-storage-identifierReferenced in:6. - Status of a permission 8. - Permissions interface (2) for a PermissionName name and an environment settings - object settings, the UA MUST return a tuple consisting - of:

-
    -
  1. name -
  2. settings’ origin -
  3. optional UA-specific data like whether settings’ browsing context has a parent browsing context, or settings’ top-level browsing context’s origin -
-
dictionary PermissionStorage#dictdef-permissionstorageReferenced in:4. 
-    Permission Registry
-   (2)5. 
-    Permission Store
-   (2) (3) (4) (5) (6) (7)9. 
-    Common permission algorithms
-   {
-  // PermissionStorage is just an explanatory device.
-  // Instances are never received from or passed to Javascript code.
-
-  required PermissionState state;
-};
-
-

The steps to retrieve a permission storage entry#retrieve-a-permission-storage-entryReferenced in:6. - Status of a permission of a permission storage identifier are as follows:

-
    -
  1. If the user agent has a PermissionStorage associated - with the permission storage identifier in its permission store, - it MUST return the PermissionStorage. -
  2. Otherwise, it MUST return undefined. -
-

The steps to create a permission storage entry#create-a-permission-storage-entryReferenced in:8. - Permissions interface for a permission storage identifier are as follows:

-
    -
  1. If the user agent has a PermissionStorage associated - with the permission storage identifier in its permission store, - it MUST overwrite it to the given PermissionStorage. -
  2. Otherwise, it MUST write the new PermissionStorage to its - permission store. -
-

The steps to delete a permission storage entry#delete-a-permission-storage-entryReferenced in:8. - Permissions interface of a permission storage identifier are as follows:

-
    -
  1. If the user agent has a PermissionStorage associated - with the permission storage identifier in its permission store, - it MUST remove it. -
-
-
-

6. Status of a permission

-
enum PermissionState#enumdef-permissionstateReferenced in:5. 
-    Permission Store
-  6. 
-    Status of a permission
-   {
-  "granted",
-  "denied",
-  "prompt",
-};
-
-

The "granted"#dom-permissionstate-grantedReferenced in:4.5. - Media Devices 6. - Status of a permission state represents - that the caller will be able - to successfuly access the feature without having the user agent asking the user’s permission.

-

The "denied"#dom-permissionstate-deniedReferenced in:4.5. - Media Devices 6. - Status of a permission state represents - that the caller will not be - able to access the feature.

-

The "prompt"#dom-permissionstate-promptReferenced in:4.5. - Media Devices 6. - Status of a permission (2) state represents - that the user agent will be asking the user’s permission if the caller tries to access the - feature. The user might grant, deny or dismiss the request.

-

The steps to retrieve the permission storage#retrieve-the-permission-storageReferenced in:6. - Status of a permission 8. - Permissions interface for a given PermissionName name are as follows:

-
    -
  1. Get a permission storage identifier for name and - the current environment settings object, and let identifier be the result. -
  2. Run the steps to retrieve a permission storage entry of identifier. -
  3. If the result of those steps are not undefined, return - it and abort these steps. -
  4. Otherwise, the user agent MUST return a default value based - on user agent’s defined heuristics. For example, {state: "prompt"} can be a default value, but it can also be based on - frequency of visits. -
-
[Exposed=(Window,Worker)]
-interface PermissionStatus#permissionstatusReferenced in:4. 
-    Permission Registry
-   (2)6. 
-    Status of a permission
-   (2) (3)8. 
-    Permissions interface
-   (2) (3)9. 
-    Common permission algorithms
-   (2) : EventTarget {
-  readonly attribute PermissionState state;
-  attribute EventHandler onchange;
-};
-
-

PermissionStatus instances are created with the following - internal slots:

-
-
[[permission]]#dom-permissionstatus-permission-slotReferenced in:6. - Status of a permission (2) (3) -
A permission. [[permission]] is always the permission named [[query]].name. -
[[query]]#dom-permissionstatus-query-slotReferenced in:6. - Status of a permission (2) (3) (4) -
A PermissionDescriptor. -
-

The steps to update the state#update-the-stateReferenced in:6. - Status of a permission 8. - Permissions interface (2) of a PermissionStatus instance status are as - follows:

-
    -
  1. Run the steps to retrieve the permission storage for status@[[query]].name, - and let storage be the result. -
  2. Run status@[[permission]]’s permission - query algorithm, passing status@[[query]], storage, and status. -
-

The steps to create a PermissionStatus#create-a-permissionstatusReferenced in:8. - Permissions interface (2) (3) for a given PermissionDescriptor permissionDesc are as follow:

-
    -
  1. Let permission be the permission named by permissionDesc.name. -
  2. - Let status be a new instance of permission’s permission result type, with the internal slots filled as: - - - - - - -
    Slot - Value -
    [[permission]] - permission -
    [[query]] - permissionDesc -
    -
  3. Return status. -
-

The state#dom-permissionstatus-stateReferenced in:6. - Status of a permission attribute MUST return the latest value that was set on the current - instance.

-

The onchange#dom-permissionstatus-onchangeReferenced in:6. - Status of a permission attribute is an event handler whose corresponding event handler event - type is change.

-

Whenever the user agent is aware that the state of a PermissionStatus instance status has changed, - it MUST asynchronously run the following steps:

-
    -
  1. Run the steps to update the state of status. -
  2. Queue a task on the permission task source to fire an event named change at status. -
-
-
- -

A Permissions instance is exposed on the navigator object for Window and Worker contexts.

-
[Exposed=(Window)]
-partial interface Navigator {
-  readonly attribute Permissions permissions;
-};
-
-
[Exposed=(Worker)]
-partial interface WorkerNavigator {
-  readonly attribute Permissions permissions;
-};
-
-
-
-

8. Permissions interface

-
[Exposed=(Window,Worker)]
-interface Permissions#permissionsReferenced in:4. 
-    Permission Registry
-   (2) (3)7. 
-    Navigator and WorkerNavigator extension
-   (2) (3) {
-  Promise<PermissionStatus> query(PermissionDescriptor permissionDesc);
-
-  Promise<PermissionStatus> request(PermissionDescriptor permissionDesc);
-
-  Promise<PermissionStatus> revoke(PermissionDescriptor permissionDesc);
-};
-
-

When the query()#dom-permissions-queryReferenced in:4. - Permission Registry 8. - Permissions interface method is invoked, - the user agent MUST run the following query a - permission algorithm, passing the parameter permissionDesc:

-
    -
  1. - If permissionDesc.name has a permission - descriptor type other than PermissionDescriptor, convert the - underlying ECMAScript object to the permission descriptor type dictionary as described in [WEBIDL], then: -
      -
    • If that operation failed, return a Promise rejected with - a TypeError and abort these steps. -
    • Otherwise, set permissionDesc to the result of the - operation. -
    -
  2. Let promise be a newly-created Promise. -
  3. Return promise and continue the following steps - asynchronously. -
  4. Run the steps to create a PermissionStatus for permissionDesc, and let status be the result. -
  5. Run the steps to update the state on status. -
  6. Resolve promise with status. -
-
If a developer wants to check multiple permissions at once, the editors - recommend the use of Promise.all(). An example can be - found in the Examples section.
-

When the request()#dom-permissions-requestReferenced in:4. - Permission Registry 8. - Permissions interface method is invoked, - the user agent MUST run the following request a - permission algorithm, passing the parameter permissionDesc:

-
    -
  1. - If permissionDesc.name has a permission - descriptor type other than PermissionDescriptor, convert the - underlying ECMAScript object to the permission descriptor type dictionary as described in [WEBIDL], then: -
      -
    • If that operation failed, return a Promise rejected with - a TypeError and abort these steps. -
    • Otherwise, set permissionDesc to the result of the - operation. -
    -
  2. Let promise be a newly-created Promise. -
  3. Return promise and continue the following steps - asynchronously. -
  4. Let permission be the permission named by permissionDesc.name. -
  5. Run the steps to create a PermissionStatus for permissionDesc, and let status be the result. -
  6. Run the steps to retrieve the permission storage for permission, and let storage be the result. -
  7. Let result be the result of promise-calling permission’s permission request algorithm with storage, permissionDesc, and status as arguments. -
  8. Resolve promise with the result of transforming result with a fulfillment handler that runs the following - steps. -
  9. Get a permission storage identifier for permissionDesc.name and the current environment settings object, and create a permission - storage entry mapping this identifier to storage. -
  10. Return status. -
-

When the revoke()#dom-permissions-revokeReferenced in:4. - Permission Registry 8. - Permissions interface method is invoked, the user agent MUST run the following revoke a permission algorithm, passing the - parameter permissionDesc:

-
    -
  1. - If permissionDesc.name has a permission - descriptor type other than PermissionDescriptor, convert the - underlying ECMAScript object to the permission descriptor type dictionary as described in [WEBIDL], then: -
      -
    • If that operation failed, return a Promise rejected with - a TypeError and abort these steps. -
    • Otherwise, set permissionDesc to the result of the - operation. -
    -
  2. Let promise be a newly-created Promise. -
  3. Return promise and continue the following steps - asynchronously. -
  4. Get a permission storage identifier for permission.name and the current environment settings object, and let identifier be - the result. -
  5. Run the steps to delete a permission storage entry using identifier. -
  6. Run permissionDesc.name’s permission revocation - algorithm. -
  7. Run the steps to create a PermissionStatus for permissionDesc, and let status be the result. -
  8. Run the steps to update the state on status. -
  9. Resolve promise with status. -
-
-
-

9. Common permission algorithms

-

The boolean permission query algorithm#boolean-permission-query-algorithmReferenced in:4. - Permission Registry , given a PermissionDescriptor permissionDesc, a PermissionStorage storage, and a PermissionStatus status, runs the following steps:

-
    -
  1. Set status.state to storage.state -
-

The boolean permission request algorithm#boolean-permission-request-algorithmReferenced in:4. - Permission Registry , given a PermissionDescriptor permission and a PermissionStatus status, runs the following steps:

-
    -
  1. TODO -
-
-
-

10. Examples

-
- -

This example uses the Permissions API to decide whether local news - should be shown using the Geolocation API or with a button offering to - add the feature.

-
<script>
-  navigator.permissions.query({name:'geolocation'}).then(function(result) {
-    if (result.state == 'granted') {
-      showLocalNewsWithGeolocation();
-    } else if (result.state == 'prompt') {
-      showButtonToEnableLocalNews();
-    }
-    // Don’t do anything if the permission was denied.
-  });
-</script>
-
-
-
- -

This example is using the "notifications" permission for a - chat application to show a notification button depending on the - permission state.

-
<script>
-  function updateNotificationButton(state) {
-    document.getElementById('chat-notification-button').disabled = (state == 'denied');
-  }
-
-  navigator.permissions.query({name:'notifications'}).then(function(result) {
-    updateNotificationButton(result.state);
-
-    result.addEventListener('change', function() {
-      updateNotificationButton(this.state);
-    });
-  });
-</script>
-
-
-
- -

This example is checking whether the page has the "geolocation" and the "notifications" permissions - using Promise.all.

-
<script>
-  Promise.all([navigator.permissions.query({name:'geolocation'}),
-               navigator.permissions.query({name:'notifications'})])
-  .then(function(result) {
-    console.log('Geolocation permission state is ' + result[0].state);
-    console.log('Notifications permission state is ' + result[1].state);
-  });
-</script>
-
-
-
- -

This example is checking whether the page has the "camera" permission for the first device in the list. Error checking omitted.

-
<script>
-  navigator.mediaDevices.enumerateDevices()
-  .then(function(devices) {
-     return navigator.permissions.query({name:'camera',
-                                         deviceId: devices[0].deviceId})
-  })
-  .then(function(result) {
-     console.log('Camera permission to first camera is ' + result.state);
-  }
-  .catch(err => console.log('Bad things happened: ' + err.name));
-</script>
-
-
-
-
-

Acknowledgments

-

The editors would like to thank Adrienne Porter Felt, Anne van - Kesteren, Domenic Denicola, Jake Archibald and Wendy Seltzer for their - help with the API design and editorial work.

-
-
-

Conformance

-

Document conventions

-

Conformance requirements are expressed with a combination of - descriptive assertions and RFC 2119 terminology. The key words “MUST”, - “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, - “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this - document are to be interpreted as described in RFC 2119. - However, for readability, these words do not appear in all uppercase - letters in this specification.

-

All of the text of this specification is normative except sections - explicitly marked as non-normative, examples, and notes. [RFC2119]

-

Examples in this specification are introduced with the words “for example” - or are set apart from the normative text with class="example", - like this:

-
- -

This is an example of an informative example.

-
-

Informative notes begin with the word “Note” and are set apart from the - normative text with class="note", like this:

-

Note, this is an informative note.

-

Conformant Algorithms

-

Requirements phrased in the imperative as part of algorithms (such as - "strip any leading space characters" or "return false and abort these - steps") are to be interpreted with the meaning of the key word ("must", - "should", "may", etc) used in introducing the algorithm.

-

Conformance requirements phrased as algorithms or specific steps can be - implemented in any manner, so long as the end result is equivalent. In - particular, the algorithms defined in this specification are intended to - be easy to understand and are not intended to be performant. Implementers - are encouraged to optimize.

- -

Index

-

Terms defined by this specification

- -

Terms defined by reference

- -

References

-

Normative References

-
-
[ECMASCRIPT] -
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/ -
[HTML] -
Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ -
[PROMISES-GUIDE] -
Domenic Denicola. Writing Promise-Using Specifications. 16 February 2016. Finding of the W3C TAG. URL: https://www.w3.org/2001/tag/doc/promises-guide -
[RFC2119] -
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 -
[UIEVENTS] -
Gary Kacmarcik; Travis Leithead. UI Events Specification. 15 December 2015. WD. URL: https://w3c.github.io/uievents/ -
[WEB-BLUETOOTH] -
Jeffrey Yasskin. Web Bluetooth. Draft Community Group Report. URL: https://webbluetoothcg.github.io/web-bluetooth/ -
[WEBIDL] -
Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 8 March 2016. CR. URL: https://heycam.github.io/webidl/ -
[WHATWG-DOM] -
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/ -
-

Informative References

-
-
[AUDIO-OUTPUT] -
Justin Uberti; Victoria Kirst. Audio Output Devices API. 10 February 2015. WD. URL: http://www.w3.org/TR/audio-output/ -
[geolocation-API] -
Andrei Popescu. Geolocation API Specification. 28 May 2015. PER. URL: http://www.w3.org/TR/geolocation-API/ -
[GETUSERMEDIA] -
Daniel Burnett; et al. Media Capture and Streams. 14 April 2015. LCWD. URL: http://www.w3.org/TR/mediacapture-streams/ -
[NOTIFICATIONS] -
Anne van Kesteren. Notifications API Standard. Living Standard. URL: https://notifications.spec.whatwg.org/ -
[PUSH-API] -
Michael van Ouwerkerk; et al. Push API. 15 December 2015. WD. URL: http://www.w3.org/TR/push-api/ -
[WEB-BACKGROUND-SYNC] -
Web Background Synchronization specification draft. URL: https://wicg.github.io/BackgroundSync/spec/ -
[WEBMIDI] -
Chris Wilson; Jussi Kalliokoski. Web MIDI API. 17 March 2015. WD. URL: http://www.w3.org/TR/webmidi/ -
-

IDL Index

-
dictionary PermissionDescriptor {
-  required PermissionName name;
-};
-
-enum PermissionName {
-  "geolocation",
-  "notifications",
-  "push",
-  "midi",
-  "camera",
-  "microphone",
-  "speaker",
-  "device-info",
-  "background-sync",
-  "bluetooth",
-};
-
-dictionary PushPermissionDescriptor : PermissionDescriptor {
-  boolean userVisibleOnly = false;
-};
-
-dictionary MidiPermissionDescriptor : PermissionDescriptor {
-  boolean sysex = false;
-};
-
-dictionary DevicePermissionDescriptor : PermissionDescriptor {
-  DOMString deviceId;
-};
-
-dictionary PermissionStorage {
-  // PermissionStorage is just an explanatory device.
-  // Instances are never received from or passed to Javascript code.
-
-  required PermissionState state;
-};
-
-enum PermissionState {
-  "granted",
-  "denied",
-  "prompt",
-};
-
-[Exposed=(Window,Worker)]
-interface PermissionStatus : EventTarget {
-  readonly attribute PermissionState state;
-  attribute EventHandler onchange;
-};
-
-[Exposed=(Window)]
-partial interface Navigator {
-  readonly attribute Permissions permissions;
-};
-
-[Exposed=(Worker)]
-partial interface WorkerNavigator {
-  readonly attribute Permissions permissions;
-};
-
-[Exposed=(Window,Worker)]
-interface Permissions {
-  Promise<PermissionStatus> query(PermissionDescriptor permissionDesc);
-
-  Promise<PermissionStatus> request(PermissionDescriptor permissionDesc);
-
-  Promise<PermissionStatus> revoke(PermissionDescriptor permissionDesc);
-};
-
-
- \ No newline at end of file diff --git a/published/FPWD.html b/published/FPWD.html deleted file mode 100644 index 2966fa0..0000000 --- a/published/FPWD.html +++ /dev/null @@ -1,1071 +0,0 @@ - - - - - The Permissions API - - - - - - -

Abstract

- The Permissions API allows a web application to be aware of - the status of a given permission, to know whether it is granted, denied - or if the user will be asked whether the permission should be granted. -

Status of This Document

- - - -

- This section describes the status of this document at the time of its publication. - Other documents may supersede this document. A list of current W3C publications and the - latest revision of this technical report can be found in the W3C technical reports index at - http://www.w3.org/TR/. -

- -

- This document was published by the Web Application Security Working Group as a First Public Working Draft. - - This document is intended to become a W3C Recommendation. - - - If you wish to make comments regarding this document, please send them to - public-webappsec@w3.org - (subscribe, - archives). - - - - - - - All comments are welcome. - - -

- - - -

- Publication as a First Public Working Draft does not imply endorsement by the W3C - Membership. This is a draft document and may be updated, replaced or obsoleted by other - documents at any time. It is inappropriate to cite this document as other than work in - progress. -

- - - -

- - This document was produced by a group operating under the - 5 February 2004 W3C Patent - Policy. - - - - - W3C maintains a public list of any patent - disclosures - - made in connection with the deliverables of the group; that page also includes - instructions for disclosing a patent. An individual who has actual knowledge of a patent - which the individual believes contains - Essential - Claim(s) must disclose the information in accordance with - section - 6 of the W3C Patent Policy. - - -

- -

This document is governed by the 1 August 2014 W3C Process Document. -

- - - - - -

Table of Contents

- -

1. Conformance

-

- As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, - and notes in this specification are non-normative. Everything else in this specification is - normative. -

-

The key words MAY, MUST, and RECOMMENDED are - to be interpreted as described in [RFC2119]. -

- -

- This specification defines conformance criteria that apply to a single - product: the user agent that implements the interfaces that - it contains. -

-

- Implementations that use ECMAScript to expose the APIs defined in this - specification MUST implement them in a manner consistent with the - ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. -

-
-
-

2. - Dependencies -

-

- The following concepts and interfaces are defined in [HTML]: -

- -

- - Promise objects are defined in [ECMASCRIPT]. -

-
-
-

3. - Scope of this document -

This section is non-normative.

-

- This document goal is to specify an API that will help developers to - handle permissions on the Web platform. Web APIs have different ways to - deal with permissions. The [notifications] API allows developers to - request a permission and check the permission status explicitly. Others - might only expose the status to web pages. Some, like [geolocation-API] - will keep the page unaware of the permission associated with the - feature. -

-

- Being able to know whether an API call is going to prompt is mandatory - in order to provide a good user experience. Unfortunately, more often - than not, those prompts can't be controlled by the developers. -

-

- The API specified in this document is meant to provide the tools so - that web applications can improve their user experience when - permissions are involved. -

-

- The solution described in this document is meant to be extensible but - isn't meant to be applicable to all the current and future permissions - available in the web platform. If you are working on a specification - that has a permission model that wouldn't fit in the model described in - this document, please contact the editors or file an issue. We would - love to hear about it. -

-

- The initial intent of this document was to allow web applications to - request and revoke permissions explicitly in addition of query the - permission status. This is an aspect of the specification that was - controversial thus removed from the current document in a spirit of - incremental changes: settling on a small API that can be improved. -

-
-
-

4. - Permission Registry -

- 
enum PermissionName {
-    "geolocation",
-    "notifications",
-    "push-notifications",
-    "midi-sysex"
-};
-

- The PermissionName enum defines the list of known - permissions. These permissions are meant to be associated with a use - case instead of one API. Thus, some permissions have a 1:1 relationship - with an API while some others might include more than one API or even a - subset of an API. -

-
Note

- For example, push-notifications is exposing the ability for a - web page to use push messages in order to show notifications. - Implementations might associate it with full usage of the Push API and - the Notifications API while others will force the callers to use the - Push API only in order to use the Notifications API. -

-

- Specifications are welcome to request a new name to be added to this - registry instead of trying to monkey patch it. -

-

- The geolocation - permission is the permission associated with the usage of the - [geolocation-API]. -

-

- The notifications - permission is the permission associated with the usage of the - [notifications] API. -

-

- The push-notifications - permission is the permission associated with the usage of the - [push-api] in order to show notifications using the [notifications] - API. -

-

- The midi-sysex permission - is the permission associated with the usage of sysex messages in the - [webmidi] API. -

-
-
-

5. - Permission definition -

- 
dictionary Permission {
-    required PermissionName name;
-};
-

- A Permission dictionary MUST contain a name field which represents the - permission's identifier. -

-

- If a permission has to be defined by more than its name, it is - RECOMMENDED to inherit from Permission dictionary and add - new fields. -

-
Note
- There are currently no permission defined in this specification using - this dictionary. It is only specified here in order to expose the - ability for the API to be extended to more complex permissions.
- For example, if the [quota-api] were to have an associated - permission, it could define a QuotaPermission dictionary extending - Permission with type and value fields. -
-
-
-

6. - Status of a permission -

- 
enum PermissionState {
-    "granted",
-    "denied",
-    "prompt"
-};
-

- The steps to retrieve the permission state of a global - object for a given permission are as follows: -

-
    -
  1. If the user agent will allow the global object to try - to access the features associated with the permission but - will prompt the user to know whether the call should succeed or fail, - the user agent MUST return prompt. -
    2. -
  2. Otherwise, if the user agent will allow the global - object to access the features associated with the - permission without prompting the user, the user - agent MUST return granted . -
    3. -
  3. Otherwise, the user agent will not allow the global - object to access the feature associated with - permission and MUST return denied . -
    4. -
-

- How the user agent decides whether a global object is - allowed or not to access some features is left as an implementation - details. However, the implementation MUST be consistent and not return - different values unless something happened (user action, expiration). -

-

- It is RECOMMENDED for implementations to use the origins of the Document or Worker when - making security decisions. Other factors MAY also apply like whether - the permission is associated with a [powerful-features] or whether - the Document is embedded. -

-
Issue 1
- The retrieve the permission state algorithm does not take into - account all the theoretically possible use cases. It tries to stay - inside the scope of the permissions described in this document.
- There are open questions about use cases where it might not work as - well: issue 8 - and issue 9. -
- 
[Exposed=(Window,Worker)]
-interface PermissionStatus : EventTarget {
-    readonly    attribute Permission      permission;
-    readonly    attribute PermissionState status;
-                attribute EventHandler    onchange;
-};
-

- The steps to update the status of a - PermissionStatus instance are as follow: -

-
    -
  1. Let status be the PermissionStatus instance - being updated. -
    2. -
  2. Run the steps to retrieve the permission state using the - status' global object and permission - attribute then set the result of those steps to the status - attribute. -
    3. -
-

- The steps to create a PermissionStatus for a given - permission are as follow: -

-
    -
  1. Let status be a PermissionStatus instance. -
    2. -
  2. Set the permission attribute to - permission. -
    3. -
  3. Run the steps to update the status on status. -
    4. -
  4. Return status. -
    5. -
-

- The permission attribute - MUST return the Permission it was initially set to - at the object creation. -

-

- The status - attribute MUST return the latest value that was set while running the - update the status steps on the current instance. -

-

- The onchange attribute is an - event handler whose corresponding event handler event - type is change. -

-

- Whenever the user agent is aware that the status of - a PermissionStatus instance has changed, it MUST - asynchronously run the following steps: -

-
    -
  1. Let permission-status be the - PermissionStatus for which the status has - changed. -
    2. -
  2. Run the steps to update the status of - permission-status. -
    3. -
  3. - Queue a task on the permission task source to - fire a simple event named change at - permission-status. -
    4. -
-
-
-

7. - Permissions interface -

- 
[Exposed=(Window,Worker)]
-interface Permissions {
-    static Promise<PermissionStatus> query ((Permission or PermissionName) permission);
-};
-

- When the - query() method is invoked, the user agent MUST run - the following steps: -

-
    -
  1. Let permission be permission argument if - permission is of type Permission, otherwise, - create a Permission instead for which name is - set to the permission argument value. -
    2. -
  2. Let promise be a newly-created Promise. -
    3. -
  3. Return promise and continue those steps asynchronously. -
    4. -
  4. Run the steps to create a PermissionStatus using the - global object and permission and resolve - promise with the result of those steps. -
    5. -
-
Note
- If a developer wants to check multiple permissions at once, the editors - recommend them to use Promises.all(). It should yield to the same - result and allow this API to stay simple. If it happens to be a very - common use case, it should be easy to extend Permissions.query() to - accept a sequence<> too. -
-
-
-

8. - Examples -

This section is non-normative.

-

- This example uses the Permissions API to decide whether local news - should be shown using the Geolocation API or a button offering that - feature should be added. -

-
Example 1
<script>
-  Permissions.query('geolocation').then(function(result) {
-    if (result.status == 'granted') {
-      showLocalNewsWithGeolocation();
-    } else if (result.status == 'prompt') {
-      showButtonToEnableLocalNews();
-    }
-    // Don't do anything if the permission was denied.
-  });
-</script>
-

- This example is using the notifications permission for a - chat application to show a notification button depending on the - permission status. -

-
Example 2
<script>
-  function updateNotificationButton(permission) {
-    document.getElementById('chat-notification-button').disabled = (permission.status == 'denied');
-  }
-
-  Permissions.query('notifications').then(function(result) {
-    updateNotificationButton(result);
-
-    result.addEventListener('change', function() {
-      updateNotificationButton(this);
-    });
-  });
-</script>
-
- -
-

A. - Acknowledgments -

-

- Thanks to Adrienne Porter Felt and Jake Archibald for their early - support and help. -

-
- - -

B. References

B.1 Normative references

[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification, Edition 6. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html -
[HTML]
Ian Hickson. HTML. Living Standard. URL: https://html.spec.whatwg.org/ -
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 -
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/ -

B.2 Informative references

[geolocation-API]
Andrei Popescu. Geolocation API Specification. 24 October 2013. W3C Recommendation. URL: http://www.w3.org/TR/geolocation-API/ -
[notifications]
John Gregg; Anne van Kesteren. Web Notifications. 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/notifications/ -
[powerful-features]
Mike West. Requirements for Powerful Features. 4 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/powerful-features/ -
[push-api]
Bryan Sullivan; Eduardo Fullea; Michael van Ouwerkerk. Push API. 7 October 2014. W3C Working Draft. URL: http://www.w3.org/TR/push-api/ -
[quota-api]
Kinuko Yasuda. Quota Management API. 5 November 2013. W3C Working Draft. URL: http://www.w3.org/TR/quota-api/ -
[webmidi]
Chris Wilson; Jussi Kalliokoski. Web MIDI API. 17 March 2015. W3C Working Draft. URL: http://www.w3.org/TR/webmidi/ -
From 47277c715fd3acac7271a18abed2f41444497152 Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 22:58:07 +0100 Subject: [PATCH 04/11] Fix bash issue with 'if []'. --- deploy.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/deploy.sh b/deploy.sh index be8e31e..00d750d 100644 --- a/deploy.sh +++ b/deploy.sh @@ -39,7 +39,8 @@ git config user.name "Travis CI" git config user.email "$COMMIT_AUTHOR_EMAIL" # If there are no changes to the compiled out (e.g. this is a README update) then just bail. -if [ -z `git diff --exit-code` ]; then +GIT_DIFF_EXIT_CODE=`git diff --exit-code` +if [ "$GIT_DIFF_EXIT_CODE" == 0 ]; then echo "No changes to the output on this push; exiting." exit 0 fi From ce4979a0221340ad60a75dc6e5a5349368d910ff Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 23:16:06 +0100 Subject: [PATCH 05/11] Use 'git status -s' to check for difference. --- deploy.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/deploy.sh b/deploy.sh index 00d750d..963d023 100644 --- a/deploy.sh +++ b/deploy.sh @@ -39,8 +39,7 @@ git config user.name "Travis CI" git config user.email "$COMMIT_AUTHOR_EMAIL" # If there are no changes to the compiled out (e.g. this is a README update) then just bail. -GIT_DIFF_EXIT_CODE=`git diff --exit-code` -if [ "$GIT_DIFF_EXIT_CODE" == 0 ]; then +if [[ -z $(git status -s) ]]; then echo "No changes to the output on this push; exiting." exit 0 fi From 93120c13ea9b8c5e330b2c0bbbceb05edc833001 Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 23:47:58 +0100 Subject: [PATCH 06/11] Other build system fixes. --- deploy.sh | 13 +- published/FPWD.html | 1071 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1077 insertions(+), 7 deletions(-) create mode 100644 published/FPWD.html diff --git a/deploy.sh b/deploy.sh index 963d023..59d3828 100644 --- a/deploy.sh +++ b/deploy.sh @@ -4,14 +4,10 @@ set -e # Exit with nonzero exit code if anything fails SOURCE_BRANCH="master" TARGET_BRANCH="gh-pages" -function doCompile { - curl https://api.csswg.org/bikeshed/ -f -F file=@index.bs > index.html; -} - # Pull requests and commits to other branches shouldn't try to deploy, just build to verify if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then echo "Skipping deploy; just doing a build." - doCompile + curl https://api.csswg.org/bikeshed/ -f -F file=@index.bs > index.html; exit 0 fi @@ -30,8 +26,11 @@ cd .. # Clean out existing contents rm -rf out/**/* || exit 0 -# Run our compile script -doCompile +# Adding back published/ dir. +cp -r published/ out/ || exit 0 + +# Re-generating. +curl https://api.csswg.org/bikeshed/ -f -F file=@index.bs > out/index.html; # Now let's go have some fun with the cloned repo cd out diff --git a/published/FPWD.html b/published/FPWD.html new file mode 100644 index 0000000..2966fa0 --- /dev/null +++ b/published/FPWD.html @@ -0,0 +1,1071 @@ + + + + + The Permissions API + + + + + + +

Abstract

+ The Permissions API allows a web application to be aware of + the status of a given permission, to know whether it is granted, denied + or if the user will be asked whether the permission should be granted. +

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

+ This document was published by the Web Application Security Working Group as a First Public Working Draft. + + This document is intended to become a W3C Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-webappsec@w3.org + (subscribe, + archives). + + + + + + + All comments are welcome. + + +

+ + + +

+ Publication as a First Public Working Draft does not imply endorsement by the W3C + Membership. This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other than work in + progress. +

+ + + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ +

This document is governed by the 1 August 2014 W3C Process Document. +

+ + + + + +

Table of Contents

+ +

1. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

The key words MAY, MUST, and RECOMMENDED are + to be interpreted as described in [RFC2119]. +

+ +

+ This specification defines conformance criteria that apply to a single + product: the user agent that implements the interfaces that + it contains. +

+

+ Implementations that use ECMAScript to expose the APIs defined in this + specification MUST implement them in a manner consistent with the + ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. +

+
+
+

2. + Dependencies +

+

+ The following concepts and interfaces are defined in [HTML]: +

+ +

+ + Promise objects are defined in [ECMASCRIPT]. +

+
+
+

3. + Scope of this document +

This section is non-normative.

+

+ This document goal is to specify an API that will help developers to + handle permissions on the Web platform. Web APIs have different ways to + deal with permissions. The [notifications] API allows developers to + request a permission and check the permission status explicitly. Others + might only expose the status to web pages. Some, like [geolocation-API] + will keep the page unaware of the permission associated with the + feature. +

+

+ Being able to know whether an API call is going to prompt is mandatory + in order to provide a good user experience. Unfortunately, more often + than not, those prompts can't be controlled by the developers. +

+

+ The API specified in this document is meant to provide the tools so + that web applications can improve their user experience when + permissions are involved. +

+

+ The solution described in this document is meant to be extensible but + isn't meant to be applicable to all the current and future permissions + available in the web platform. If you are working on a specification + that has a permission model that wouldn't fit in the model described in + this document, please contact the editors or file an issue. We would + love to hear about it. +

+

+ The initial intent of this document was to allow web applications to + request and revoke permissions explicitly in addition of query the + permission status. This is an aspect of the specification that was + controversial thus removed from the current document in a spirit of + incremental changes: settling on a small API that can be improved. +

+
+
+

4. + Permission Registry +

+ 
enum PermissionName {
+    "geolocation",
+    "notifications",
+    "push-notifications",
+    "midi-sysex"
+};
+

+ The PermissionName enum defines the list of known + permissions. These permissions are meant to be associated with a use + case instead of one API. Thus, some permissions have a 1:1 relationship + with an API while some others might include more than one API or even a + subset of an API. +

+
Note

+ For example, push-notifications is exposing the ability for a + web page to use push messages in order to show notifications. + Implementations might associate it with full usage of the Push API and + the Notifications API while others will force the callers to use the + Push API only in order to use the Notifications API. +

+

+ Specifications are welcome to request a new name to be added to this + registry instead of trying to monkey patch it. +

+

+ The geolocation + permission is the permission associated with the usage of the + [geolocation-API]. +

+

+ The notifications + permission is the permission associated with the usage of the + [notifications] API. +

+

+ The push-notifications + permission is the permission associated with the usage of the + [push-api] in order to show notifications using the [notifications] + API. +

+

+ The midi-sysex permission + is the permission associated with the usage of sysex messages in the + [webmidi] API. +

+
+
+

5. + Permission definition +

+ 
dictionary Permission {
+    required PermissionName name;
+};
+

+ A Permission dictionary MUST contain a name field which represents the + permission's identifier. +

+

+ If a permission has to be defined by more than its name, it is + RECOMMENDED to inherit from Permission dictionary and add + new fields. +

+
Note
+ There are currently no permission defined in this specification using + this dictionary. It is only specified here in order to expose the + ability for the API to be extended to more complex permissions.
+ For example, if the [quota-api] were to have an associated + permission, it could define a QuotaPermission dictionary extending + Permission with type and value fields. +
+
+
+

6. + Status of a permission +

+ 
enum PermissionState {
+    "granted",
+    "denied",
+    "prompt"
+};
+

+ The steps to retrieve the permission state of a global + object for a given permission are as follows: +

+
    +
  1. If the user agent will allow the global object to try + to access the features associated with the permission but + will prompt the user to know whether the call should succeed or fail, + the user agent MUST return prompt. +
    2. +
  2. Otherwise, if the user agent will allow the global + object to access the features associated with the + permission without prompting the user, the user + agent MUST return granted . +
    3. +
  3. Otherwise, the user agent will not allow the global + object to access the feature associated with + permission and MUST return denied . +
    4. +
+

+ How the user agent decides whether a global object is + allowed or not to access some features is left as an implementation + details. However, the implementation MUST be consistent and not return + different values unless something happened (user action, expiration). +

+

+ It is RECOMMENDED for implementations to use the origins of the Document or Worker when + making security decisions. Other factors MAY also apply like whether + the permission is associated with a [powerful-features] or whether + the Document is embedded. +

+
Issue 1
+ The retrieve the permission state algorithm does not take into + account all the theoretically possible use cases. It tries to stay + inside the scope of the permissions described in this document.
+ There are open questions about use cases where it might not work as + well: issue 8 + and issue 9. +
+ 
[Exposed=(Window,Worker)]
+interface PermissionStatus : EventTarget {
+    readonly    attribute Permission      permission;
+    readonly    attribute PermissionState status;
+                attribute EventHandler    onchange;
+};
+

+ The steps to update the status of a + PermissionStatus instance are as follow: +

+
    +
  1. Let status be the PermissionStatus instance + being updated. +
    2. +
  2. Run the steps to retrieve the permission state using the + status' global object and permission + attribute then set the result of those steps to the status + attribute. +
    3. +
+

+ The steps to create a PermissionStatus for a given + permission are as follow: +

+
    +
  1. Let status be a PermissionStatus instance. +
    2. +
  2. Set the permission attribute to + permission. +
    3. +
  3. Run the steps to update the status on status. +
    4. +
  4. Return status. +
    5. +
+

+ The permission attribute + MUST return the Permission it was initially set to + at the object creation. +

+

+ The status + attribute MUST return the latest value that was set while running the + update the status steps on the current instance. +

+

+ The onchange attribute is an + event handler whose corresponding event handler event + type is change. +

+

+ Whenever the user agent is aware that the status of + a PermissionStatus instance has changed, it MUST + asynchronously run the following steps: +

+
    +
  1. Let permission-status be the + PermissionStatus for which the status has + changed. +
    2. +
  2. Run the steps to update the status of + permission-status. +
    3. +
  3. + Queue a task on the permission task source to + fire a simple event named change at + permission-status. +
    4. +
+
+
+

7. + Permissions interface +

+ 
[Exposed=(Window,Worker)]
+interface Permissions {
+    static Promise<PermissionStatus> query ((Permission or PermissionName) permission);
+};
+

+ When the + query() method is invoked, the user agent MUST run + the following steps: +

+
    +
  1. Let permission be permission argument if + permission is of type Permission, otherwise, + create a Permission instead for which name is + set to the permission argument value. +
    2. +
  2. Let promise be a newly-created Promise. +
    3. +
  3. Return promise and continue those steps asynchronously. +
    4. +
  4. Run the steps to create a PermissionStatus using the + global object and permission and resolve + promise with the result of those steps. +
    5. +
+
Note
+ If a developer wants to check multiple permissions at once, the editors + recommend them to use Promises.all(). It should yield to the same + result and allow this API to stay simple. If it happens to be a very + common use case, it should be easy to extend Permissions.query() to + accept a sequence<> too. +
+
+
+

8. + Examples +

This section is non-normative.

+

+ This example uses the Permissions API to decide whether local news + should be shown using the Geolocation API or a button offering that + feature should be added. +

+
Example 1
<script>
+  Permissions.query('geolocation').then(function(result) {
+    if (result.status == 'granted') {
+      showLocalNewsWithGeolocation();
+    } else if (result.status == 'prompt') {
+      showButtonToEnableLocalNews();
+    }
+    // Don't do anything if the permission was denied.
+  });
+</script>
+

+ This example is using the notifications permission for a + chat application to show a notification button depending on the + permission status. +

+
Example 2
<script>
+  function updateNotificationButton(permission) {
+    document.getElementById('chat-notification-button').disabled = (permission.status == 'denied');
+  }
+
+  Permissions.query('notifications').then(function(result) {
+    updateNotificationButton(result);
+
+    result.addEventListener('change', function() {
+      updateNotificationButton(this);
+    });
+  });
+</script>
+
+ +
+

A. + Acknowledgments +

+

+ Thanks to Adrienne Porter Felt and Jake Archibald for their early + support and help. +

+
+ + +

B. References

B.1 Normative references

[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification, Edition 6. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html +
[HTML]
Ian Hickson. HTML. Living Standard. URL: https://html.spec.whatwg.org/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 +
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/ +

B.2 Informative references

[geolocation-API]
Andrei Popescu. Geolocation API Specification. 24 October 2013. W3C Recommendation. URL: http://www.w3.org/TR/geolocation-API/ +
[notifications]
John Gregg; Anne van Kesteren. Web Notifications. 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/notifications/ +
[powerful-features]
Mike West. Requirements for Powerful Features. 4 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/powerful-features/ +
[push-api]
Bryan Sullivan; Eduardo Fullea; Michael van Ouwerkerk. Push API. 7 October 2014. W3C Working Draft. URL: http://www.w3.org/TR/push-api/ +
[quota-api]
Kinuko Yasuda. Quota Management API. 5 November 2013. W3C Working Draft. URL: http://www.w3.org/TR/quota-api/ +
[webmidi]
Chris Wilson; Jussi Kalliokoski. Web MIDI API. 17 March 2015. W3C Working Draft. URL: http://www.w3.org/TR/webmidi/ +
From 287fd26b0b7300c5ec32761af3e81ebb77ac4db1 Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 23:51:12 +0100 Subject: [PATCH 07/11] deploy_key.enc isn't in out/ --- deploy.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy.sh b/deploy.sh index 59d3828..6e8df5d 100644 --- a/deploy.sh +++ b/deploy.sh @@ -53,7 +53,7 @@ ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key" ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv" ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR} ENCRYPTED_IV=${!ENCRYPTED_IV_VAR} -openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in deploy_key.enc -out deploy_key -d +openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in ../deploy_key.enc -out deploy_key -d chmod 600 deploy_key eval `ssh-agent -s` ssh-add deploy_key From 2a41056732ddc79d1f56113a43b98c4cad46c51a Mon Sep 17 00:00:00 2001 From: Mounir Lamouri Date: Wed, 27 Apr 2016 23:58:24 +0100 Subject: [PATCH 08/11] New deploy_key.enc --- deploy_key.enc | Bin 3248 -> 3248 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/deploy_key.enc b/deploy_key.enc index 72f382850da84d90b8e935c876837cf925137aec..90f1d6338710d6ea8ae2961e459399964a2bee25 100644 GIT binary patch literal 3248 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 literal 3248 zcmV;h3{Ufs73&IHrOQP$!}1vKjh}`fD_k@tVX<3xrw>x5gyeAusIYLyEm8Y-8$ZeS zukWY1O6yi=+Oc%Vyot=o_g~{^GJ}pi>~W(2am`<=Zp)U-NLdis6Z=BYaAOEqblvwk zq3*O=O17ya4WOxaBxJ!n=%+smjZ~gNrFih;28WS-dBW!+w_-3xa<6I2iKrma^?Y1}mXsD27*RfA9L zh#M^w65<81&uqmCLX~pw^7Yq@UU8jqH@?8S4raJshV)z^kL1pDL~DzEortwE<(EfK zX)Lg?@b#~}Y>f-@Yy_}4FyMZk3~sJQQJ#hzM}e*YfkntWw*NOv*GJ{&#I>E9R@U(h z(W^C8zqyO)ljt!;td(9i`V1sQA=nntgJD(;bzaD15`*|e95OM{u&fd&b=Mt^V zI+b9sgvpQVB2jKxiD>AEk!Li5qwczbK4J->^E0nv6(834knc?V`Q*QxPiw;4TG? z-P1^*rMk0~C-xK8mvHY_W3pU{r|5*oq3G1V2&`>LZy`PdcyTGbsY%bB#x zS)F6G7ml%m0kyNO)}302-xFY(J$S4{x?+|+XQ{W~0@PuC1j)>U%44MA-|Cn%e+ALz znC{OmR7a6jyQg)&eos>XP1KP5I4au+vmM9Z_yC394e57r7V3%X$!~PwW3lF%R;2L= z6wypz^gD}koL^5OFXDf(&0`{KzLJ2)(|*4?nvW-)yQZ8+GlYbH_qcLdtkk6WuFiE z6WE&^l{a$3bjJ{HS!cSMsPczf23Sn)oM?d61l6{cI2RG`1x&@T+jE0_i%tpu6Omp` zH#xrIm>eA4sNz?=(EZhJ)Zh4KRfIRebQrit-y7yRo)pppD1cP7j!RMWgET?w_Iv}N z4-nl-;>*0go&u9+Cs;S#H9Z5fe7wdellsN(|0xY3`o1{mNyuQ*QEL3VlPAPX(`>Sb zC}JmjvxyOcpa90krJ}S7Iavd*W^Y zFTqFXql$EVR0*!M7V9bq#WE{5CY}<)V$UQCMj^c^gwI^}V2pW#stphx1Wfy`n~TfF zrW?IBxpUCDP&B@v%e*z|=7sfdv`w`V=GdZkQ4O`A(+;?Hs z>j{(p+qJqN1ye9SqvrxYrYK#!w}FIhG4VfqSjV9-eOl|$OPy)}V&swbY-l^FEiMok z4PH~6&6^IlGYTIZ7oY zKb^izO_V=E#roYH!GWo(+R>mqwv7OFax`w?afF&m*%VD4Mu}qyrwJzJ#*8-fO+Um1 zZzkU>g{c5|&tkeu_NaEN1}%^a+p{2pirR)=0)lWTP=(SX=OZ9S(O`_CF^?0LL~ z35gZ`&=b9UDyr`-Q~1w^tVv-r;X&on?u!f3-=1_WB@z4Q@w{yJ>Mjw7_wC%Y&!do= z5a?W&JX_a(cb3R3!+4rlb=4!e;gX3)Q)9zV{s)xd24V63Ymb4p-RS#QngfYO1aeMm zZC}7J6Tu!t)G1q~u0%`vi}%J%i~;Lz>)qeip@Wb@bmZt2gc&Nf_A^VK&+_vwdpE^L zIC(!X#l(a7pcgRH`*=Xu$}%oBggz(#){w%QIslX}2mbdzB>4crSZX~;RWqydu41vy zX`5fBLr1qjG4)tpPPbhl@GBYsRI=*i&1m$-Bi@MR(fitRdvEg;nGceNn(@bU|Gxsk zZisa8cFF@JZxFGimah~aTL>PrRbU1Mhkq+sK` zf!QOJhR6giQA1^T226UZMq7vHxF9ASBSd8)Ou?#E0byM7(kKpmQX7zEN(#&l6blT- z6BKW{h}lS_{nx&4i<>Ns5+We*e`9nF$~C=DM|t9G+WZ+Gl2m*RV+SnH}2G z*%0KHDs+?AOYVRCc=u_m){ynsIuYNvZ5%Ysc zsqc2qYu`Y9HRLx=t-@96qy#^yu8WDBe({B~nr6AKi~GM53gE}gSw=MT zF2+FXA_Rwe97b88e?E&oO%iX?OTY#vfSc7a1z!0eD{x7wvANw=e=8|0)yEvk^c5F} zdPkI%eAkI1xM7cQCLuBlsyjv*i8nvE@Uc$FC2fnYO@ShCY~E*wG=jy5b-CCyJTYQDTCvydx1R4ztQ-X znnXy)o{hr#-9~`cC^L%PeE{B8_Ge0Pqv{KV@r^^xpfLLuy@8mIj`xde(Ubh>k;J;9 zf5}(%8tu(IcZ)X0mw)vYxIw#}1wF<%1#@koPR~t9oT~Yry|2ZF$5wPmNEIFYq~s{n zU<*7<{#7R1HhVu46Btioerne?adu8Ixl-rS%ZV5&+F~mdz%|hrxx%?mgWxVU!89#U z{J6)?pCELKkLRW9)saV&8eYo}=XQCqvA`Zl4rGh^Oah$|(}m|YBmSe@_~uR=6X3=^ z1N(A3WvWPI3ujT>N`uTHmY@dT_0JGAptBVhtN;j}Z2tD(7VD4d>7?Ovmw+TeHW;1w z1-n5L1hrr>tDi-BT2Ft)H(RSahYZbO;BeI3udqBc=~i8>fCD;lUM9Z#oj7+jPRErd z@|lVK=p262k4ZNhm|^?4sj{8tQLS)_BTKixey~buIfO+Z9ah=|a70lxv!Sq@RRsTa zi(k-wr_OQ4NBrc;U%uyFlPnvez4PQb(z82MhK#vSrLOX0hI~`6d4TYBN{M~_` Date: Thu, 28 Apr 2016 00:07:25 +0100 Subject: [PATCH 09/11] Use 'rm -rf out/*' instead of 'rm -rf out/**/*'. The latter seems to not work consistently and behave as out/*/*. --- deploy.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy.sh b/deploy.sh index 6e8df5d..d8e6ce5 100644 --- a/deploy.sh +++ b/deploy.sh @@ -24,7 +24,7 @@ git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH cd .. # Clean out existing contents -rm -rf out/**/* || exit 0 +rm -rf out/* || exit 0 # Adding back published/ dir. cp -r published/ out/ || exit 0 From cbf87109119319fd271bb54682f1a26fa0d7bc70 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Mon, 25 Apr 2016 14:12:16 -0700 Subject: [PATCH 10/11] Define an algorithm to update the permission storage. Also move the "retrieve the permission storage" algorithm to a common location for algorithms that other specs can use, and rename it to "the 'name' permission's storage" to make it easier to call. --- index.bs | 146 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 109 insertions(+), 37 deletions(-) diff --git a/index.bs b/index.bs index 67afe7e..1f18f49 100644 --- a/index.bs +++ b/index.bs @@ -39,6 +39,7 @@ spec: promises-guide; urlPrefix: https://www.w3.org/2001/tag/doc/promises-guide# spec: html type: dfn text: browsing context + text: current settings object text: environment settings object text: event handler text: event handler event type @@ -439,6 +440,103 @@ spec: webidl it MUST remove it. + +
+

Storage Manipulation Algorithms

+ +

+ Other specifications can use the algorithms defined in this section to + manipulate the permission store from their algorithms. +

+ +
+

+ The [[notifications]] API can check for the user having granted + permission using: +

+
+ If the {{"notifications"}} permission's storage's + {{PermissionStorage/state}} is not {{"granted"}}, reject + promise with a {{TypeError}} exception and terminate these + substeps. +
+ +

+ The [[notifications]] API can update the stored permission using: +

+
+ … ask the user whether showing notifications for the current + settings object’s origin is acceptable. Update the permission + storage storage for {{"notifications"}} by setting + storage.{{PermissionStorage/state}} to + {{"granted"}} if it is acceptable, or {{"denied"}} otherwise. +
+

+ Note that the steps inside Update the permission storage may run + multiple times on permission storages that aren't equal to what `"name"` + permission's storage returns, particularly to handle the + difference between temporary and permanent permissions. Do not rely on + previously-read values for storage or produce side-effects + on anything other than storage inside these steps. +

+
+ +

+ The {{PermissionName}} name permission's + storage is the result of the following algorithm (formerly named the + retrieve the permission storage algorithm): +

+
    +
  1. + Get a permission storage identifier for name and + the current environment settings object, and let + identifier be the result. +
    2. +
  2. Run the steps to retrieve a permission storage entry of + identifier. + + Issue(86): This needs to let the UA select which of potentially many + permission stores to read from. +
    3. +
  3. If the result of those steps are not undefined, return + it and abort these steps. +
    4. +
  4. Otherwise, the user agent MUST return a default value based + on user agent's defined heuristics. For example, {state: + {{"prompt"}}} can be a default value, but it can also be based on + frequency of visits. +
    5. +
+ +

+ When an algorithm says to update the permission storage + storage for a {{PermissionName}} name using some + instructions, where "storage" is a placeholder for an + arbitrarily-named variable,the UA MUST: +

+
    +
  1. + Get a permission storage identifier for name and + the current environment settings object, and let + identifier be the result. +
    2. +
  2. + Set the user's variable storage to the name + permission's storage . +
    3. +
  3. + Run the instructions. + + Issue(86): This needs to be able to happen multiple times at the UA's + discretion in order to update both temporary and origin-wide permission + stores. +
    4. +
  4. + Create a permission storage entry for identifier with + the value from the user's variable storage. +
    5. +
+

@@ -468,28 +566,7 @@ spec: webidl will be asking the user's permission if the caller tries to access the feature. The user might grant, deny or dismiss the request.

-

- The steps to retrieve the permission storage for a given - {{PermissionName}} name are as follows: -

-
    -
  1. - Get a permission storage identifier for name and - the current environment settings object, and let - identifier be the result. -
    2. -
  2. Run the steps to retrieve a permission storage entry of - identifier. -
    3. -
  3. If the result of those steps are not undefined, return - it and abort these steps. -
    4. -
  4. Otherwise, the user agent MUST return a default value based - on user agent's defined heuristics. For example, {state: - {{"prompt"}}} can be a default value, but it can also be based on - frequency of visits. -
    5. -
+ 
     [Exposed=(Window,Worker)]
     interface PermissionStatus : EventTarget {
@@ -522,9 +599,9 @@ spec: webidl
     follows:
   

   
    
-    
  1. Run the steps to retrieve the permission storage for
-      status@{{[[query]]}}.{{PermissionDescriptor/name}},
-      and let storage be the result.
+    
  2. Let storage be the
+    status@{{[[query]]}}.{{PermissionDescriptor/name}}
+    permission's storage.
     
    3. 
     
  3. Run status@{{[[permission]]}}'s permission
     query algorithm, passing status@{{[[query]]}},
@@ -706,25 +783,20 @@ spec: webidl
     
  4. Run the steps to create a PermissionStatus for
     permissionDesc, and let status be the result.
     
    5. 
-    
  5. Run the steps to retrieve the permission storage for
-    permission, and let storage be the result.
+    
  6. Let storage be the permission permission's
+    storage.
     
    7. 
     
  7. Let result be the result of promise-calling
       permission's permission request algorithm with
       storage, permissionDesc, and status
       as arguments.
+
+      Note: The permission request algorithm is responsible to update
+      the permission storage if necessary.
     
    8. 
     
  8. Resolve promise with the result of transforming
-    result with a fulfillment handler that runs the following
-    steps.
-    
    9. 
-    
  9. 
-      Get a permission storage identifier for
-      permissionDesc.name and the current
-      environment settings object, and create a permission
-      storage entry mapping this identifier to storage.
-    
    10. 
-    
  10. Return status.
+      result with a fulfillment handler that returns
+      status.
     
    11. 
   

   


From 93eb530c2a70c2fae502dd1cb8e4ecffa4251461 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Mon, 25 Apr 2016 14:46:34 -0700
Subject: [PATCH 11/11] Add shorthands for permissions with just `state` in
 their storage.

---
 index.bs | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 61 insertions(+), 7 deletions(-)

diff --git a/index.bs b/index.bs
index 1f18f49..97301c7 100644
--- a/index.bs
+++ b/index.bs
@@ -455,10 +455,25 @@ spec: webidl
         permission using:
       

       

-        If the {{"notifications"}} permission's storage's
-        {{PermissionStorage/state}} is not {{"granted"}}, reject
-        promise with a {{TypeError}} exception and terminate these
-        substeps.
+        If the {{"notifications"}} permission's state is not
+        {{"granted"}}, reject promise with a {{TypeError}} exception
+        and terminate these substeps.
+      

+
+      

+        The [[web-bluetooth]] API can check for the user having granted
+        permission to use a particular device using:
+      

+      

+        
    
+          
  1. Let storage be the {{"bluetooth"}} permission's storage.
+          
    2. 
+          
  2. 
+            If device is the {{AllowedBluetoothDevice/[[device]]}}
+            for one of the {{AllowedBluetoothDevice}}s in
+            storage.allowedDevices, …
+          
    3. 
+        

       

 
       

@@ -467,10 +482,29 @@ spec: webidl
       

         … ask the user whether showing notifications for the current
         settings object’s origin is acceptable. Update the permission
-        storage storage for {{"notifications"}} by setting
-        storage.{{PermissionStorage/state}} to
-        {{"granted"}} if it is acceptable, or {{"denied"}} otherwise.
+        state for {{"notifications"}} to {{"granted"}} if it is acceptable,
+        or {{"denied"}} otherwise.
       

+
+      

+        The [[web-bluetooth]] API can remove permission to access a particular
+        device using:
+      

+      

+        Update the permission storage storage for
+        {{"bluetooth"}} by running the following sub-steps:
+        
    
+          
  1. 
+            If there is an allowedDevice in
+            storage.{{BluetoothPermissionStorage/allowedDevices}}
+            with
+            allowedDevice.{{AllowedBluetoothDevice/[[device]]}}
+            equal to device, remove it.
+          
    2. 
+        

+      

+
+
       

         Note that the steps inside Update the permission storage may run
         multiple times on permission storages that aren't equal to what `"name"`
@@ -536,6 +570,26 @@ spec: webidl
         the value from the user's variable storage.
       
     
+
+    

+      We define shorthands for permissions that only need to access their
+      {{PermissionStorage/state}}:
+    

+    
    
+      
  • 
+        The {{PermissionName}} name permission's
+        state is the name permission's storage's
+        {{PermissionStorage/state}}.
+      
    • 
+      
  • 
+        To update the permission state for a
+        {{PermissionName}} name to a {{PermissionState}}
+        state means to update the permission storage
+        storage for name by setting
+        storage.{{PermissionStorage/state}} to
+        state.
+      
    • 
+