From 05272a4e0b7275bcbeac48f7e79fb81cc3d9aac4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Mon, 14 Feb 2022 05:46:16 +0000 Subject: [PATCH] Editorial: group algorithms into own section SHA: acd129602e6583ceadb800e14aa7c6a2532c4021 Reason: push, by @marcoscaceres Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- index.html | 797 +++++++++++++++++++++++++++-------------------------- 1 file changed, 402 insertions(+), 395 deletions(-) diff --git a/index.html b/index.html index e39699a..29ac3a4 100644 --- a/index.html +++ b/index.html @@ -370,41 +370,43 @@

Powerful features
  1. 2.2.1 Aspects -
  • 2.3 +
  • 3. + Specifying a powerful feature +
  • 4. + Algorithms to interface with permissions +
    1. 4.1 Reading the current permission state -
    2. 2.4 +
    3. 4.2 Requesting permission to use a powerful feature -
    4. 2.5 +
    5. 4.3 Prompt the user to choose -
    6. 2.6 +
    7. 4.4 Reacting to users revoking permission -
  • 3. - Specifying a powerful feature -
  • 4. +
  • 5. Permissions API -
    1. 4.1 +
      1. 5.1 Extensions to the Navigator and WorkerNavigator interfaces -
      2. 4.2 +
      3. 5.2 Permissions interface -
        1. 4.2.1 +
          1. 5.2.1 query() method -
        2. 4.3 +
      4. 5.3 PermissionStatus interface -
        1. 4.3.1 +
          1. 5.3.1 Creating instances -
          2. 4.3.2 +
          3. 5.3.2 name attribute -
          4. 4.3.3 +
          5. 5.3.3 state attribute -
          6. 4.3.4 +
          7. 5.3.4 onchange attribute -
          8. 4.3.5 +
          9. 5.3.5 Garbage collection -
      5. 5. +
  • 6. Powerful features registry -
    1. 5.1 +
      1. 6.1 Screen wake lock -
    2. 6. Conformance
    3. A. +
  • 7. Conformance
  • A. Relationship to the Permissions Policy specification
  • B. Automated testing @@ -634,182 +636,19 @@

    -

    2.3 - Reading the current permission state -

    - -

    - To get the current - permission state, given a name name and an optional - environment settings object settings: -

    -
      -
    1. Let descriptor be a newly-created PermissionDescriptor - whose name is initialized with name. -
      2. -
    2. Return the permission state of descriptor and settings. -
      3. -
    -

    - A descriptor's permission state for an - optional environment settings object settings is the result of the following - algorithm, which returns one of "granted", - "prompt", or "denied": -

    -
      -
    1. If settings wasn't passed, set it to the current settings object. -
      2. -
    2. If settings is a non-secure context, return "denied". -
      3. -
    3. If there exists a policy-controlled feature identified by descriptor's - name and settings has an associated Document named - document, run the following step: -
        -
      1. If document is not allowed to use the feature identified by - descriptor's name return "denied". -
        2. -
      -
      4. -
    4. If there was a previous invocation of this algorithm with the same descriptor and - settings, returning previousResult, and the UA has not received new information - about the user's intent since that invocation, return previousResult. -
      5. -
    5. Return whichever of the following options most accurately reflects the user's intent - for the calling algorithm, taking into account any permission state constraints for descriptor's name: -
      -
      - succeed without prompting the user -
      -
      - "granted" -
      -
      - show the user a prompt to decide whether to succeed -
      -
      - "prompt" -
      -
      - fail without prompting the user -
      -
      - "denied" -
      -
      -
      6. -
    -
    Issue 278: Safari returns different results for current permission state

    Safari is the only known UA that returns different results from this algorithm for different settings objects with the same origin. We should test which of the several possible settings objects it uses.

    -

    - As a shorthand, a PermissionName name's permission state is the - permission state of a PermissionDescriptor with its - name member set to name. -

    -
    -

    2.4 - Requesting permission to use a powerful feature -

    - -
    Note

    - Spec authors, please note that algorithms in this section can wait for user input; so - they shouldn't be used from other algorithms running on the main thread. -

    -

    - To request permission to use a descriptor, the UA must perform the - following steps. This algorithm returns either "granted" or - "denied". -

    -
      -
    1. Let current state be the descriptor's permission state. -
      2. -
    2. If current state is not "prompt", return current - state and abort these steps. -
      3. -
    3. Ask the user for express permission for the calling algorithm to use the - powerful feature described by descriptor. -
      4. -
    4. If the user grants permission, return "granted"; otherwise return - "denied". The user's interaction may provide new information about - the user's intent for this realm and other realms - with the same origin. -
      Note

      - This is intentionally vague about the details of the permission UI and how the UA - infers user intent. UAs should be able to explore lots of UI within this framework. -

      -
      5. -
    -

    - As a shorthand, requesting permission to use a PermissionName name, is the - same as requesting permission to use a PermissionDescriptor with its - name member set to name. -

    -
    -

    2.5 - Prompt the user to choose -

    - -

    - To prompt the user to choose one of several options associated with a - descriptor, the UA must perform the following steps. This algorithm returns either - "denied" or one of the options. -

    -
      -
    1. If descriptor's permission state is "denied", return - "denied" and abort these steps. -
      2. -
    2. If descriptor's permission state is "granted", the UA - may return one of options and abort these steps. If the UA returns without prompting, - then subsequent prompts for the user to choose - from the same set of options with the same descriptor must return the same option, - unless the UA receives new information about the user's intent. -
      3. -
    3. Ask the user to choose one of the options or deny permission, and wait for them to - choose. If the calling algorithm specified extra information to include in the prompt, - include it. -
      4. -
    4. If the user chose an option, return it; otherwise return - "denied". If the user's interaction indicates they intend this choice - to apply to other realms, then treat this this as new information about the user's - intent for other realms with the same origin. -
      Note

      - This is intentionally vague about the details of the permission UI and how the UA - infers user intent. UAs should be able to explore lots of UI within this framework. -

      -
      5. -
    -

    - As a shorthand, prompting the user to choose from options associated with a - PermissionName name, is the same as prompting the user to choose from those - options associated with a PermissionDescriptor with its name - member set to name. -

    -
    -

    2.6 - Reacting to users revoking permission -

    - -

    - When the UA learns that the user no longer intends to grant permission for a realm to use a feature, react to the user revoking permission - by: -

    -
      -
    1. - Queue a task on the Realm's settings object's responsible event loop to run that feature's permission revocation algorithm. -
      2. -
    -

    3. Specifying a powerful feature

    - Please register newly specified powerful features in the + Please register newly specified powerful features in the Registry of Powerful Features. Doing so also provides this Working Group an opportunity to provide feedback and check that integration with this specification is done effectively.

    - Each powerful feature has the following permission-related algorithms and types. - When the defaults are not suitable for a particular powerful feature, a specification + Each powerful feature has the following permission-related algorithms and types. + When the defaults are not suitable for a particular powerful feature, a specification MAY override below algorithms and types below.

    @@ -818,16 +657,16 @@

    - PermissionDescriptor or one of its subtypes. If unspecified, this defaults to - PermissionDescriptor. + PermissionDescriptor or one of its subtypes. If unspecified, this defaults to + PermissionDescriptor.

    The feature can define a partial order on descriptor instances. If descriptorA is stronger than descriptorB, then if descriptorA's - permission state is "granted", descriptorB's permission - state must also be "granted", and if descriptorB's - permission state is "denied", descriptorA's permission - state must also be "denied". + permission state is "granted", descriptorB's permission + state must also be "granted", and if descriptorB's + permission state is "denied", descriptorA's permission + state must also be "denied".

    {name: "midi", sysex: true} ("midi-with-sysex") is @@ -841,15 +680,15 @@

    permission state constraints:
    - Constraints on the values that the UA can return as a descriptor's permission + Constraints on the values that the UA can return as a descriptor's permission state. Defaults to no constraints beyond the user's intent.
    extra permission data type:
    -
    Note

    - Some powerful features have more information associated with them than just a +

    Note

    + Some powerful features have more information associated with them than just a PermissionState. For example, getUserMedia() needs to determine which cameras the user has granted the current realm record permission to access. Each of these features defines an extra permission data type. If a DOMString name names one of these features, then @@ -861,7 +700,7 @@

  • If settings wasn't passed, set it to the current settings object.
  • If there was a previous invocation of this algorithm with the same name and - settings, returning previousResult, and the UA has not received new information + settings, returning previousResult, and the UA has not received new information about the user's intent since that invocation, return previousResult.
  • Return the instance of name's extra permission data type @@ -879,7 +718,7 @@

    constraints:
    - Constraints on the values that the UA can return as a powerful feature's extra permission data. Defaults to no constraints beyond the user's intent. + Constraints on the values that the UA can return as a powerful feature's extra permission data. Defaults to no constraints beyond the user's intent.
    A permission result type: @@ -901,12 +740,12 @@

    permission query algorithm.

    - The default permission query algorithm, given a PermissionDescriptor + The default permission query algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:

      -
    1. Set status.state to permissionDesc's permission state. +
    2. Set status.state to permissionDesc's permission state.

    • @@ -917,7 +756,7 @@

    Takes no arguments. Updates any other parts of the implementation that need to be kept - in sync with changes in the results of permission states or extra permission data, and then react to the user revoking permission. + in sync with changes in the results of permission states or extra permission data, and then react to the user revoking permission.

    If unspecified, this defaults to running react to the user revoking permission. @@ -928,7 +767,7 @@

    - Specifications that define one or more powerful features SHOULD suggest a + Specifications that define one or more powerful features SHOULD suggest a permission lifetime that is best suited for the particular feature. Some guidance on determining the lifetime of a permission is noted below, with a strong emphasis on user privacy. If no lifetime is specified, the user agent @@ -938,15 +777,15 @@

    When the permission lifetime expires for an origin:

      -
    1. Set the permission back to its default permission state (e.g. setting it back +
    2. Set the permission back to its default permission state (e.g. setting it back to "prompt").
      3. -
    3. For each browsing context associated with the origin (if any), queue a global task on the permissions task source with the browsing context's global object to run the permission revocation algorithm. +
    4. For each browsing context associated with the origin (if any), queue a global task on the permissions task source with the browsing context's global object to run the permission revocation algorithm.
    -
    Note: Determining the lifetime of a permission

    - A default powerful feature is a powerful feature with all + A default powerful feature is a powerful feature with all of the above types and algorithms defaulted.

    -

    4. +

    4. + Algorithms to interface with permissions +

    + +

    4.1 + Reading the current permission state +

    + +

    + To get the current + permission state, given a name name and an optional + environment settings object settings: +

    +
      +
    1. Let descriptor be a newly-created PermissionDescriptor + whose name is initialized with name. +
      2. +
    2. Return the permission state of descriptor and settings. +
      3. +
    +

    + A descriptor's permission state for an + optional environment settings object settings is the result of the following + algorithm, which returns one of "granted", + "prompt", or "denied": +

    +
      +
    1. If settings wasn't passed, set it to the current settings object. +
      2. +
    2. If settings is a non-secure context, return "denied". +
      3. +
    3. If there exists a policy-controlled feature identified by descriptor's + name and settings has an associated Document named + document, run the following step: +
        +
      1. If document is not allowed to use the feature identified by + descriptor's name return "denied". +
        2. +
      +
      4. +
    4. If there was a previous invocation of this algorithm with the same descriptor and + settings, returning previousResult, and the UA has not received new information + about the user's intent since that invocation, return previousResult. +
      5. +
    5. Return whichever of the following options most accurately reflects the user's intent + for the calling algorithm, taking into account any permission state constraints for descriptor's name: +
      +
      + succeed without prompting the user +
      +
      + "granted" +
      +
      + show the user a prompt to decide whether to succeed +
      +
      + "prompt" +
      +
      + fail without prompting the user +
      +
      + "denied" +
      +
      +
      6. +
    +
    Issue 278: Safari returns different results for current permission state

    Safari is the only known UA that returns different results from this algorithm for different settings objects with the same origin. We should test which of the several possible settings objects it uses.

    +

    + As a shorthand, a PermissionName name's permission state is the + permission state of a PermissionDescriptor with its + name member set to name. +

    +
    +

    4.2 + Requesting permission to use a powerful feature +

    + +
    Note

    + Spec authors, please note that algorithms in this section can wait for user input; so + they shouldn't be used from other algorithms running on the main thread. +

    +

    + To request permission to use a descriptor, the UA must perform the + following steps. This algorithm returns either "granted" or + "denied". +

    +
      +
    1. Let current state be the descriptor's permission state. +
      2. +
    2. If current state is not "prompt", return current + state and abort these steps. +
      3. +
    3. Ask the user for express permission for the calling algorithm to use the + powerful feature described by descriptor. +
      4. +
    4. If the user grants permission, return "granted"; otherwise return + "denied". The user's interaction may provide new information about + the user's intent for this realm and other realms + with the same origin. +
      Note

      + This is intentionally vague about the details of the permission UI and how the UA + infers user intent. UAs should be able to explore lots of UI within this framework. +

      +
      5. +
    +

    + As a shorthand, requesting permission to use a PermissionName name, is the + same as requesting permission to use a PermissionDescriptor with its + name member set to name. +

    +
    +

    4.3 + Prompt the user to choose +

    + +

    + To prompt the user to choose one of several options associated with a + descriptor, the UA must perform the following steps. This algorithm returns either + "denied" or one of the options. +

    +
      +
    1. If descriptor's permission state is "denied", return + "denied" and abort these steps. +
      2. +
    2. If descriptor's permission state is "granted", the UA + may return one of options and abort these steps. If the UA returns without prompting, + then subsequent prompts for the user to choose + from the same set of options with the same descriptor must return the same option, + unless the UA receives new information about the user's intent. +
      3. +
    3. Ask the user to choose one of the options or deny permission, and wait for them to + choose. If the calling algorithm specified extra information to include in the prompt, + include it. +
      4. +
    4. If the user chose an option, return it; otherwise return + "denied". If the user's interaction indicates they intend this choice + to apply to other realms, then treat this this as new information about the user's + intent for other realms with the same origin. +
      Note

      + This is intentionally vague about the details of the permission UI and how the UA + infers user intent. UAs should be able to explore lots of UI within this framework. +

      +
      5. +
    +

    + As a shorthand, prompting the user to choose from options associated with a + PermissionName name, is the same as prompting the user to choose from those + options associated with a PermissionDescriptor with its name + member set to name. +

    +
    +

    4.4 + Reacting to users revoking permission +

    + +

    + When the UA learns that the user no longer intends to grant permission for a realm to use a feature, react to the user revoking permission + by: +

    +
      +
    1. + Queue a task on the Realm's settings object's responsible event loop to run that feature's permission revocation algorithm. +
      2. +
    +
    +
    +

    5. Permissions API -

    + 

    WebIDL[Exposed=(Window)]
 partial interface Navigator {
@@ -1144,9 +1151,9 @@ 
    
       No
     
   
-  
    4.2 
+  
    5.2 
           Permissions interface
-        
    
+        
    
         
         
    WebIDL[Exposed=(Window,Worker)]
 interface Permissions {
@@ -1202,9 +1209,9 @@ 
    
       No
     
   
-  
    4.2.1 
+  
    5.2.1 
             query() method
-          
    
+          
    
           
           
    
             When the query() method is invoked, the user agent MUST run the
@@ -1287,9 +1294,9 @@ 
    
       No
     
   
-  
    4.3 
+  
    5.3 
           PermissionStatus interface
-        
    
+        
    
         
         
    WebIDL[Exposed=(Window,Worker)]
 interface PermissionStatus : EventTarget {
@@ -1312,9 +1319,9 @@ 
    
           represent the concepts of granted, denied, and
           prompt respectively.
         
    
-        
    4.3.1 
+        
    5.3.1 
             Creating instances
-          
    
+          
    
           
           
    
             To create a PermissionStatus for a given
@@ -1384,9 +1391,9 @@ 
    
       No
     
   
-  
    4.3.2 
+  
    5.3.2 
             name attribute
-          
    
+          
    
           
           
    
             The name attribute returns the value it was initialized to.
@@ -1438,9 +1445,9 @@ 
    
       No
     
   
-  
    4.3.3 
+  
    5.3.3 
             state attribute
-          
    
+          
    
           
           
    
             The state attribute returns the latest value that was set on the current
@@ -1493,9 +1500,9 @@ 
    
       No
     
   
-  
    4.3.4 
+  
    5.3.4 
             onchange attribute
-          
    
+          
    
           
           
    
             The onchange attribute is an event handler whose corresponding
@@ -1517,9 +1524,9 @@

    • -

    4.3.5 +

    5.3.5 Garbage collection -

    +

    A PermissionStatus object MUST NOT be garbage collected if it has an event listener whose type is change. @@ -1941,9 +1948,9 @@

    60+ -

    5. +

    6. Powerful features registry -

    + 

    WebIDLenum PermissionName {
   "accelerometer",
@@ -2025,9 +2032,9 @@ 
    
         The xr-spatial-tracking enum value identifies the WebXR Device API Device API
         powerful feature.
       
    
-      
    5.1 
+      
    6.1 
           Screen wake lock
-        
    
+        
    
         
         
    
           The screen-wake-lock enum value identifies the Screen Wake Lock API
@@ -2039,7 +2046,7 @@
    -

    6. 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.

    +

    7. 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, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 @@ -2260,7 +2267,7 @@

    Referenced in: