{"action":"created","comment":{"url":"https://api.github.com/repos/w3c/permissions/pulls/comments/64837231","id":64837231,"diff_hunk":"@@ -101,21 +118,190 @@ spec: webidl\n </section>\n <section>\n   <h2 id=\"permission-descriptor\">\n-    Permission descriptor\n+    Descriptions of permission requests\n   </h2>\n   <pre class='idl' title=''>\n     dictionary PermissionDescriptor {\n       required PermissionName name;\n     };\n   </pre>\n   <p>\n-    A permission is described by a name and other properties that depend on the\n-    name. The simplest permissions require only a name, but some others have\n-    more detailed structure that requires more information to describe it. In\n-    that case, they should define a customized <a>permission descriptor\n-    type</a> dictionary that inherits from {{PermissionDescriptor}}.\n+    Each powerful feature has one or more aspects that websites may request\n+    permission to access. To describe these aspects, each feature defines a\n+    subtype of {{PermissionDescriptor}} to be its <a>permission descriptor\n+    type</a>.\n   </p>\n+\n+  <div class=\"example\" id=\"example-descriptors\">\n+    <p>\n+      The {{\"midi\"}} feature has two aspects: access to normal messages, and\n+      access to system exclusive messages. Thus, its permission descriptor type\n+      is:\n+    </p>\n+    <pre highlight=\"idl\">\n+      dictionary MidiPermissionDescriptor : PermissionDescriptor {\n+        boolean sysex = false;\n+      };\n+    </pre>\n+    <p>\n+      The {{\"camera\"}} feature lets sites access whatever cameras are connected\n+      to the user's device. Thus, its descriptor type is:\n+    </p>\n+    <pre highlight=\"idl\">\n+      dictionary DevicePermissionDescriptor : PermissionDescriptor {\n+        DOMString deviceId;\n+      };\n+    </pre>\n+    <p>\n+      General access to cameras is represented by `{name: 'camera'}`, while\n+      access to a particular camera is represented by `{name: 'camera',\n+      deviceId: cameraId}`.\n+    </p>\n+  </div>\n+</section>\n+<section>\n+  <h2 id=\"permission-operations\">Permission states</h2>\n+  <p>\n+    The user agent is responsible for tracking what powerful features each\n+    <a>realm</a> has the user's permission to use. Other specifications can use\n+    the operations defined in this section to retrieve the UA's notion of what\n+    permissions are granted or denied, and to ask the user to grant or deny more\n+    permissions.\n+  </p>\n+\n+  <p>\n+    Other specifications can also add more constraints on the UA's behavior in\n+    these algorithms.\n+  </p>\n+\n+  <p>\n+    Within this section, |descriptor| is an instance of the <a>permission\n+    descriptor type</a> of the powerful feature named by\n+    <code>|descriptor|.{{PermissionDescriptor/name}}</code>.\n+  </p>\n+\n+  <section>\n+    <h3 id=\"reading-current-states\">Reading the current permission state</h3>\n+    <p>\n+      |descriptor|'s <dfn export>permission state</dfn> is one\n+      of {{\"granted\"}}, {{\"prompt\"}}, or {{\"denied\"}}, indicating respectively\n+      if the calling algorithm should succeed without prompting the user, show\n+      the user a prompt to decide whether to succeed, or fail without prompting\n+      the user. The UA must return whichever of these values most accurately\n+      reflects the user's intent. Successive uses of |descriptor|'s <a>permission\n+      state</a> with the same <a>current settings object</a> should return the\n+      same value, unless the UA receives new information about the user's\n+      intent.\n+    </p>\n+\n+    <p class=\"issue\" id=\"issue-current-entry-incumbent-or-relevant\">\n+      Safari is the only known UA that returns different results from this\n+      algorithm for different settings objects with the same origin. We should\n+      test which of the <a\n+      href=\"https://html.spec.whatwg.org/multipage/webappapis.html#realms-settings-objects-global-objects\">several\n+      possible settings objects</a> it uses.\n+    </p>\n+\n+    <p>\n+      Some powerful features have more information associated with them than\n+      just a {{PermissionState}}. For example, {{MediaDevices/getUserMedia()}}\n+      needs to determine <em>which</em> cameras the user has granted the\n+      <a>current realm</a> permission to access. Each of these features defines\n+      an <a>extra permission data type</a>, and then a {{PermissionName}} |name|'s\n+      <dfn export>extra permission data</dfn> is the instance of that type\n+      matching the UA's impression of the user's intent. Successive uses of\n+      |name|'s <a>extra permission data</a> should return the same value, unless\n+      the UA receives new information about the user's intent.\n+    </p>\n+  </section>\n+  <section>\n+    <h3 id=\"requesting-more-permission\">Requesting more permission</h3>\n+\n+    <div algorithm=\"request-permission-to-use\">\n+      <p>\n+        To <dfn export>request permission to use</dfn> a |descriptor|, the UA\n+        must perform the following steps. Note that these steps may wait for\n+        user input, so they should not be used from other algorithms running on\n+        the main thread. This algorithm returns either {{\"granted\"}} or\n+        {{\"denied\"}}.\n+      </p>\n+      <ol>\n+        <li>\n+          If |descriptor|'s <a>permission state</a> is not {{\"prompt\"}}, return\n+          that value and abort these steps.\n+        </li>\n+        <li>\n+          Show the user a prompt asking their permission for the calling\n+          algorithm to use powerful feature described by |descriptor|.\n+        </li>\n+        <li>\n+          If the user grants permission, return {{\"granted\"}}; otherwise return\n+          {{\"denied\"}}. Depending on the details of the user's interaction, the\n+          UA may also treat this as new information about the user's intent for\n+          other realms with the same origin.\n+\n+          <p class=\"note\">\n+            This is intentionally vague about the details of the permission UI\n+            and how the UA infers user intent. UAs should be able to explore\n+            lots of UI within this framework.\n+          </p>\n+        </li>\n+      </ol>\n+    </div>\n+\n+    <div algorithm=\"prompt-user-to-choose\">\n+      <p>\n+        To <dfn export>prompt the user to choose</dfn> one of several options","path":"index.bs","position":null,"original_position":183,"commit_id":"7c3530fc55c21036e5572d4f2b75ee719bec7d6b","original_commit_id":"247f065b3c9d8d80a94fefbcee1b83488700000c","user":{"login":"jyasskin","id":83420,"avatar_url":"https://avatars.githubusercontent.com/u/83420?v=3","gravatar_id":"","url":"https://api.github.com/users/jyasskin","html_url":"https://github.com/jyasskin","followers_url":"https://api.github.com/users/jyasskin/followers","following_url":"https://api.github.com/users/jyasskin/following{/other_user}","gists_url":"https://api.github.com/users/jyasskin/gists{/gist_id}","starred_url":"https://api.github.com/users/jyasskin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jyasskin/subscriptions","organizations_url":"https://api.github.com/users/jyasskin/orgs","repos_url":"https://api.github.com/users/jyasskin/repos","events_url":"https://api.github.com/users/jyasskin/events{/privacy}","received_events_url":"https://api.github.com/users/jyasskin/received_events","type":"User","site_admin":false},"body":"You mean `<var>` them? Done.","created_at":"2016-05-26T23:18:49Z","updated_at":"2016-05-26T23:18:50Z","html_url":"https://github.com/w3c/permissions/pull/97#discussion_r64837231","pull_request_url":"https://api.github.com/repos/w3c/permissions/pulls/97","_links":{"self":{"href":"https://api.github.com/repos/w3c/permissions/pulls/comments/64837231"},"html":{"href":"https://github.com/w3c/permissions/pull/97#discussion_r64837231"},"pull_request":{"href":"https://api.github.com/repos/w3c/permissions/pulls/97"}}},"pull_request":{"url":"https://api.github.com/repos/w3c/permissions/pulls/97","id":71464965,"html_url":"https://github.com/w3c/permissions/pull/97","diff_url":"https://github.com/w3c/permissions/pull/97.diff","patch_url":"https://github.com/w3c/permissions/pull/97.patch","issue_url":"https://api.github.com/repos/w3c/permissions/issues/97","number":97,"state":"open","locked":false,"title":"Give the UA permission to return anything it wants from query().","user":{"login":"jyasskin","id":83420,"avatar_url":"https://avatars.githubusercontent.com/u/83420?v=3","gravatar_id":"","url":"https://api.github.com/users/jyasskin","html_url":"https://github.com/jyasskin","followers_url":"https://api.github.com/users/jyasskin/followers","following_url":"https://api.github.com/users/jyasskin/following{/other_user}","gists_url":"https://api.github.com/users/jyasskin/gists{/gist_id}","starred_url":"https://api.github.com/users/jyasskin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jyasskin/subscriptions","organizations_url":"https://api.github.com/users/jyasskin/orgs","repos_url":"https://api.github.com/users/jyasskin/repos","events_url":"https://api.github.com/users/jyasskin/events{/privacy}","received_events_url":"https://api.github.com/users/jyasskin/received_events","type":"User","site_admin":false},"body":"This option is the most straightforward about giving the UA nearly complete flexibility. The main constraint is that the result should only change when the UA gets new information about the user's intent, but we don't say what constitutes new information. This version also gives some examples ([media](https://api.csswg.org/bikeshed/?url=https://raw.githubusercontent.com/jyasskin/permissions/ua-can-return-anything/index.bs#media-devices) and [durable storage](https://api.csswg.org/bikeshed/?url=https://raw.githubusercontent.com/jyasskin/permissions/ua-can-return-anything/index.bs#persistent-storage)) of constraining permission behavior further on a per-API basis.\r\n\r\nPreview at https://api.csswg.org/bikeshed/?url=https://raw.githubusercontent.com/jyasskin/permissions/ua-can-return-anything/index.bs","created_at":"2016-05-25T21:19:39Z","updated_at":"2016-05-26T23:18:50Z","closed_at":null,"merged_at":null,"merge_commit_sha":"9c54aefbb87de2ad0bde4f1ea14851d464024e70","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/w3c/permissions/pulls/97/commits","review_comments_url":"https://api.github.com/repos/w3c/permissions/pulls/97/comments","review_comment_url":"https://api.github.com/repos/w3c/permissions/pulls/comments{/number}","comments_url":"https://api.github.com/repos/w3c/permissions/issues/97/comments","statuses_url":"https://api.github.com/repos/w3c/permissions/statuses/7c3530fc55c21036e5572d4f2b75ee719bec7d6b","head":{"label":"jyasskin:ua-can-return-anything","ref":"ua-can-return-anything","sha":"7c3530fc55c21036e5572d4f2b75ee719bec7d6b","user":{"login":"jyasskin","id":83420,"avatar_url":"https://avatars.githubusercontent.com/u/83420?v=3","gravatar_id":"","url":"https://api.github.com/users/jyasskin","html_url":"https://github.com/jyasskin","followers_url":"https://api.github.com/users/jyasskin/followers","following_url":"https://api.github.com/users/jyasskin/following{/other_user}","gists_url":"https://api.github.com/users/jyasskin/gists{/gist_id}","starred_url":"https://api.github.com/users/jyasskin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jyasskin/subscriptions","organizations_url":"https://api.github.com/users/jyasskin/orgs","repos_url":"https://api.github.com/users/jyasskin/repos","events_url":"https://api.github.com/users/jyasskin/events{/privacy}","received_events_url":"https://api.github.com/users/jyasskin/received_events","type":"User","site_admin":false},"repo":{"id":53459395,"name":"permissions","full_name":"jyasskin/permissions","owner":{"login":"jyasskin","id":83420,"avatar_url":"https://avatars.githubusercontent.com/u/83420?v=3","gravatar_id":"","url":"https://api.github.com/users/jyasskin","html_url":"https://github.com/jyasskin","followers_url":"https://api.github.com/users/jyasskin/followers","following_url":"https://api.github.com/users/jyasskin/following{/other_user}","gists_url":"https://api.github.com/users/jyasskin/gists{/gist_id}","starred_url":"https://api.github.com/users/jyasskin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jyasskin/subscriptions","organizations_url":"https://api.github.com/users/jyasskin/orgs","repos_url":"https://api.github.com/users/jyasskin/repos","events_url":"https://api.github.com/users/jyasskin/events{/privacy}","received_events_url":"https://api.github.com/users/jyasskin/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jyasskin/permissions","description":"Permissions API","fork":true,"url":"https://api.github.com/repos/jyasskin/permissions","forks_url":"https://api.github.com/repos/jyasskin/permissions/forks","keys_url":"https://api.github.com/repos/jyasskin/permissions/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jyasskin/permissions/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jyasskin/permissions/teams","hooks_url":"https://api.github.com/repos/jyasskin/permissions/hooks","issue_events_url":"https://api.github.com/repos/jyasskin/permissions/issues/events{/number}","events_url":"https://api.github.com/repos/jyasskin/permissions/events","assignees_url":"https://api.github.com/repos/jyasskin/permissions/assignees{/user}","branches_url":"https://api.github.com/repos/jyasskin/permissions/branches{/branch}","tags_url":"https://api.github.com/repos/jyasskin/permissions/tags","blobs_url":"https://api.github.com/repos/jyasskin/permissions/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jyasskin/permissions/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jyasskin/permissions/git/refs{/sha}","trees_url":"https://api.github.com/repos/jyasskin/permissions/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jyasskin/permissions/statuses/{sha}","languages_url":"https://api.github.com/repos/jyasskin/permissions/languages","stargazers_url":"https://api.github.com/repos/jyasskin/permissions/stargazers","contributors_url":"https://api.github.com/repos/jyasskin/permissions/contributors","subscribers_url":"https://api.github.com/repos/jyasskin/permissions/subscribers","subscription_url":"https://api.github.com/repos/jyasskin/permissions/subscription","commits_url":"https://api.github.com/repos/jyasskin/permissions/commits{/sha}","git_commits_url":"https://api.github.com/repos/jyasskin/permissions/git/commits{/sha}","comments_url":"https://api.github.com/repos/jyasskin/permissions/comments{/number}","issue_comment_url":"https://api.github.com/repos/jyasskin/permissions/issues/comments{/number}","contents_url":"https://api.github.com/repos/jyasskin/permissions/contents/{+path}","compare_url":"https://api.github.com/repos/jyasskin/permissions/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jyasskin/permissions/merges","archive_url":"https://api.github.com/repos/jyasskin/permissions/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jyasskin/permissions/downloads","issues_url":"https://api.github.com/repos/jyasskin/permissions/issues{/number}","pulls_url":"https://api.github.com/repos/jyasskin/permissions/pulls{/number}","milestones_url":"https://api.github.com/repos/jyasskin/permissions/milestones{/number}","notifications_url":"https://api.github.com/repos/jyasskin/permissions/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jyasskin/permissions/labels{/name}","releases_url":"https://api.github.com/repos/jyasskin/permissions/releases{/id}","deployments_url":"https://api.github.com/repos/jyasskin/permissions/deployments","created_at":"2016-03-09T01:50:36Z","updated_at":"2016-03-09T01:50:37Z","pushed_at":"2016-05-26T23:18:08Z","git_url":"git://github.com/jyasskin/permissions.git","ssh_url":"git@github.com:jyasskin/permissions.git","clone_url":"https://github.com/jyasskin/permissions.git","svn_url":"https://github.com/jyasskin/permissions","homepage":null,"size":214,"stargazers_count":0,"watchers_count":0,"language":"HTML","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"gh-pages"}},"base":{"label":"w3c:master","ref":"master","sha":"0d518a51e67b12433d433c5bcae28b7664f13334","user":{"login":"w3c","id":379216,"avatar_url":"https://avatars.githubusercontent.com/u/379216?v=3","gravatar_id":"","url":"https://api.github.com/users/w3c","html_url":"https://github.com/w3c","followers_url":"https://api.github.com/users/w3c/followers","following_url":"https://api.github.com/users/w3c/following{/other_user}","gists_url":"https://api.github.com/users/w3c/gists{/gist_id}","starred_url":"https://api.github.com/users/w3c/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/w3c/subscriptions","organizations_url":"https://api.github.com/users/w3c/orgs","repos_url":"https://api.github.com/users/w3c/repos","events_url":"https://api.github.com/users/w3c/events{/privacy}","received_events_url":"https://api.github.com/users/w3c/received_events","type":"Organization","site_admin":false},"repo":{"id":24997088,"name":"permissions","full_name":"w3c/permissions","owner":{"login":"w3c","id":379216,"avatar_url":"https://avatars.githubusercontent.com/u/379216?v=3","gravatar_id":"","url":"https://api.github.com/users/w3c","html_url":"https://github.com/w3c","followers_url":"https://api.github.com/users/w3c/followers","following_url":"https://api.github.com/users/w3c/following{/other_user}","gists_url":"https://api.github.com/users/w3c/gists{/gist_id}","starred_url":"https://api.github.com/users/w3c/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/w3c/subscriptions","organizations_url":"https://api.github.com/users/w3c/orgs","repos_url":"https://api.github.com/users/w3c/repos","events_url":"https://api.github.com/users/w3c/events{/privacy}","received_events_url":"https://api.github.com/users/w3c/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/w3c/permissions","description":"Permissions API","fork":false,"url":"https://api.github.com/repos/w3c/permissions","forks_url":"https://api.github.com/repos/w3c/permissions/forks","keys_url":"https://api.github.com/repos/w3c/permissions/keys{/key_id}","collaborators_url":"https://api.github.com/repos/w3c/permissions/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/w3c/permissions/teams","hooks_url":"https://api.github.com/repos/w3c/permissions/hooks","issue_events_url":"https://api.github.com/repos/w3c/permissions/issues/events{/number}","events_url":"https://api.github.com/repos/w3c/permissions/events","assignees_url":"https://api.github.com/repos/w3c/permissions/assignees{/user}","branches_url":"https://api.github.com/repos/w3c/permissions/branches{/branch}","tags_url":"https://api.github.com/repos/w3c/permissions/tags","blobs_url":"https://api.github.com/repos/w3c/permissions/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/w3c/permissions/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/w3c/permissions/git/refs{/sha}","trees_url":"https://api.github.com/repos/w3c/permissions/git/trees{/sha}","statuses_url":"https://api.github.com/repos/w3c/permissions/statuses/{sha}","languages_url":"https://api.github.com/repos/w3c/permissions/languages","stargazers_url":"https://api.github.com/repos/w3c/permissions/stargazers","contributors_url":"https://api.github.com/repos/w3c/permissions/contributors","subscribers_url":"https://api.github.com/repos/w3c/permissions/subscribers","subscription_url":"https://api.github.com/repos/w3c/permissions/subscription","commits_url":"https://api.github.com/repos/w3c/permissions/commits{/sha}","git_commits_url":"https://api.github.com/repos/w3c/permissions/git/commits{/sha}","comments_url":"https://api.github.com/repos/w3c/permissions/comments{/number}","issue_comment_url":"https://api.github.com/repos/w3c/permissions/issues/comments{/number}","contents_url":"https://api.github.com/repos/w3c/permissions/contents/{+path}","compare_url":"https://api.github.com/repos/w3c/permissions/compare/{base}...{head}","merges_url":"https://api.github.com/repos/w3c/permissions/merges","archive_url":"https://api.github.com/repos/w3c/permissions/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/w3c/permissions/downloads","issues_url":"https://api.github.com/repos/w3c/permissions/issues{/number}","pulls_url":"https://api.github.com/repos/w3c/permissions/pulls{/number}","milestones_url":"https://api.github.com/repos/w3c/permissions/milestones{/number}","notifications_url":"https://api.github.com/repos/w3c/permissions/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/w3c/permissions/labels{/name}","releases_url":"https://api.github.com/repos/w3c/permissions/releases{/id}","deployments_url":"https://api.github.com/repos/w3c/permissions/deployments","created_at":"2014-10-09T16:02:09Z","updated_at":"2016-04-29T20:52:17Z","pushed_at":"2016-05-26T23:18:09Z","git_url":"git://github.com/w3c/permissions.git","ssh_url":"git@github.com:w3c/permissions.git","clone_url":"https://github.com/w3c/permissions.git","svn_url":"https://github.com/w3c/permissions","homepage":null,"size":208,"stargazers_count":22,"watchers_count":22,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":13,"mirror_url":null,"open_issues_count":37,"forks":13,"open_issues":37,"watchers":22,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/w3c/permissions/pulls/97"},"html":{"href":"https://github.com/w3c/permissions/pull/97"},"issue":{"href":"https://api.github.com/repos/w3c/permissions/issues/97"},"comments":{"href":"https://api.github.com/repos/w3c/permissions/issues/97/comments"},"review_comments":{"href":"https://api.github.com/repos/w3c/permissions/pulls/97/comments"},"review_comment":{"href":"https://api.github.com/repos/w3c/permissions/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/w3c/permissions/pulls/97/commits"},"statuses":{"href":"https://api.github.com/repos/w3c/permissions/statuses/7c3530fc55c21036e5572d4f2b75ee719bec7d6b"}}}}
{"actor":{"display_login":"jyasskin"}}