From 75ef57e52d2734b98055ef9489bceb8d36867837 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= <caceres_m@apple.com>
Date: Fri, 8 Mar 2024 12:24:55 +1100
Subject: [PATCH] Editorial: define permission states consistently (#400)

---
 index.html | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/index.html b/index.html
index 9813d7b..0f39d41 100644
--- a/index.html
+++ b/index.html
@@ -218,16 +218,17 @@ <h3>
         </p>
         <dl data-sort="">
           <dt>
-            <dfn class="export" data-dfn-for="permission">Prompt</dfn>:
+            <dfn class="export" data-lt="prompt" data-dfn-for="permission">"prompt"</dfn>:
           </dt>
           <dd>
             The user has not given [=express permission=] to use the feature (i.e., it's the same
-            as [=permission/denied=]). It also means that if a caller attempts to use the feature,
-            the [=user agent=] will either be prompting the user for permission or access to the
-            feature will be [=permission/denied=].
+            as [=permission/"denied"=]). It also means that if a caller attempts to use the
+            feature, the [=user agent=] will either be prompting the user for permission or access
+            to the feature will be [=permission/"denied"=].
           </dd>
           <dt>
-            <dfn class="export" data-local-lt="grant" data-dfn-for="permission">Granted</dfn>:
+            <dfn class="export" data-lt="granted" data-local-lt="grant" data-dfn-for=
+            "permission">"granted"</dfn>:
           </dt>
           <dd>
             The user, or the user agent on the user's behalf, has given [=express permission=] to
@@ -235,7 +236,7 @@ <h3>
             the [=user agent=] asking the user's permission.
           </dd>
           <dt>
-            <dfn class="export" data-dfn-for="permission">Denied</dfn>:
+            <dfn class="export" data-lt="denied" data-dfn-for="permission">"denied"</dfn>:
           </dt>
           <dd>
             The user, or the user agent on the user's behalf, has denied access to this [=powerful
@@ -259,7 +260,7 @@ <h3>
         </aside>
         <p data-cite="ECMAScript">
           Every [=permission=] has a <dfn class="export" data-dfn-for="permission">lifetime</dfn>,
-          which is the duration for which a particular permission remains [=permission/granted=]
+          which is the duration for which a particular permission remains [=permission/"granted"=]
           before it reverts back to its [=permission/default state=]. A [=permission/lifetime=]
           could be until a particular [=ECMAScript/Realm=] is destroyed, until a particular
           [=top-level browsing context=] is destroyed, a particular amount of time, or be infinite.
@@ -269,9 +270,9 @@ <h3>
         </p>
         <p>
           Every permission has a <dfn data-for="permission">default state</dfn> (usually
-          [=permission/prompt=]), which is the [=permission/state=] that the permission is in when
-          the user has not yet given [=express permission=] to use the [=feature=] or it has been
-          reset because its [=permission/lifetime=] has expired.
+          [=permission/"prompt"=]), which is the [=permission/state=] that the permission is in
+          when the user has not yet given [=express permission=] to use the [=feature=] or it has
+          been reset because its [=permission/lifetime=] has expired.
         </p>
       </section>
       <section>
@@ -387,8 +388,9 @@ <h2>
           [=document=] is [=allowed to use=] a given feature. That is, a powerful feature can only
           request [=express permission=] from a user if the [=document=] has permission delegated
           to it via the corresponding [=policy-controlled feature=] (see example below). Subsequent
-          access to the feature is determined by the user having [=permission/granted=] permission,
-          or by satisfying some criteria that is equivalent to a permission [=permission/grant=].
+          access to the feature is determined by the user having [=permission/"granted"=]
+          permission, or by satisfying some criteria that is equivalent to a permission
+          [=permission/grant=].
         </p>
         <aside class="example" title="Powerful features are policy-controlled features">
           <p>
@@ -701,7 +703,7 @@ <h2>
           </p>
           <ol>
             <li>Set the permission back to its default [=permission state=] (e.g., by setting it
-            back to "[=permission/prompt=]").
+            back to [=permission/"prompt"=]).
             </li>
             <li>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
@@ -1068,8 +1070,8 @@ <h3 id="permissionstatus-interface">
         </p>
         <p data-dfn-for="PermissionState">
           The "<dfn>granted</dfn>", "<dfn>denied</dfn>", and "<dfn>prompt</dfn>" enum values
-          represent the concepts of [=permission/granted=], [=permission/denied=], and
-          [=permission/prompt=] respectively.
+          represent the concepts of [=permission/"granted"=], [=permission/"denied"=], and
+          [=permission/"prompt"=] respectively.
         </p>
         <section>
           <h4>
@@ -1210,7 +1212,7 @@ <h2 id="relationship-to-permissions-policy">
       <p>
         Finally, it's not possible for a powerful feature to ever become "granted" through any
         means provided by the [[[Permissions-Policy]]] specification. The only way that a
-        [=powerful feature=] can be [=permission/granted=] is by the user giving [=express
+        [=powerful feature=] can be [=permission/"granted"=] is by the user giving [=express
         permission=] or by some user agent policy.
       </p>
     </section>
@@ -1880,7 +1882,7 @@ <h2 id="privacy-considerations">
         An adversary could use a [=permission state=] as an element in creating a "fingerprint"
         corresponding to an end-user. Although an adversary can already determine the state of a
         permission by actually using the API, that often leads to a UI prompt being presented to
-        the end-user (if the permission was not already [=permission/granted=]). Even though this
+        the end-user (if the permission was not already [=permission/"granted"=]). Even though this
         API doesn't expose new fingerprinting information to websites, it makes it easier for an
         adversary to have discreet access to this information.
       </p>