From 8230b6a209f15b24eaf1bd6e15d52a717353e88b Mon Sep 17 00:00:00 2001
From: Thiago Perrotta <tperrotta@chromium.org>
Date: Fri, 3 Nov 2023 11:30:07 +0100
Subject: [PATCH] DRAFT: Introduce Browser Permissions

Bug: #587
Spec: https://www.w3.org/TR/permissions/
---
 index.bs | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 107 insertions(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 4d01fe352..59f327d94 100644
--- a/index.bs
+++ b/index.bs
@@ -210,6 +210,14 @@ spec: HR-TIME; urlPrefix: https://w3c.github.io/hr-time/
 spec: RFC4648; urlPrefix: https://tools.ietf.org/html/rfc4648
   type: dfn
     text: Base64 Encode; url: section-4
+spec: PERMISSIONS; urlPrefix: https://www.w3.org/TR/permissions/
+  type: dfn
+    text: permission descriptor; url: #dom-permissiondescriptor
+    text: permission name; url: #permission-name // TODO
+    text: permission state; url: #dom-permissionstate
+    text: permission status; url: #permission-status // TODO
+    text: permissions; url: #permissions
+    text: set permission; url: #set-permission-command
 spec: CSS-VALUES-3; urlPrefix: https://drafts.csswg.org/css-values-3/
   type: dfn
     text: absolute lengths; url: #absolute-lengths
@@ -3963,6 +3971,104 @@ opened</dfn> steps given |window|, |type|, |message|, and optional |default valu
 
 </div>
 
+## The permissions Module ## {#module-permissions}
+
+The <dfn export for=modules>permissions</dfn> module contains commands and
+events relating to browser [=/permissions=]. [[!PERMISSIONS]]
+
+### Definition ### {#module-permissions-definition}
+
+[=remote end definition=]
+
+<pre class="cddl remote-cddl">
+
+PermissionsCommand = (
+  permissions.SetPermission
+)
+
+TODO: Add more commands: QueryPermission, ResetPermission, ResetAllPermissions, etc.
+
+</pre>
+
+### Types ### {#module-permissions-types}
+
+#### The permissions.PermissionDescriptor Type #### {#type-permissions-PermissionDescriptor}
+
+<pre class="cddl local-cddl">
+permissions.PermissionDescriptor = {
+  type: "permissionDescriptor",
+  name: text,
+}
+</pre>
+
+The <code>permissions.PermissionDescriptor</code> type represents a [=permission descriptor=].
+
+#### The permissions.PermissionState Type #### {#type-permissions-PermissionState}
+
+<pre class="cddl local-cddl">
+permissions.PermissionState = "granted" / "denied" / "prompt"
+</pre>
+
+The <code>permissions.PermissionState</code> type represents a [=permission state=].
+
+### Commands ### {#module-permissions-commands}
+
+#### The permissions.setPermission Command ####  {#command-permissions-setPermission}
+
+The <dfn export for=commands>permissions.setPermission</dfn> command simulates
+user modification of a {{PermissionDescriptor}}'s [=permission state=].
+
+<dl>
+   <dt>Command Type</dt>
+   <dd>
+    <pre class="cddl remote-cddl">
+      permissions.setPermission = (
+        method: "permissions.setPermission",
+        params: permissions.SetPermissionParameters
+      )
+
+      permissions.SetPermissionParameters = {
+        descriptor: permissions.PermissionDescriptor,
+        state: permissions.PermissionState,
+        ? context: browsingContext.BrowsingContext,
+        ? origin: text,
+      }
+    </pre>
+   </dd>
+   <dt>Result Type</dt>
+   <dd>
+    <pre class="cddl">
+     EmptyResult
+    </pre>
+   </dd>
+</dl>
+
+<div algorithm="remote end steps for permissions.setPermission">
+
+The [=remote end steps=] with |session| and |command parameters| are:
+
+1. Let |descriptor| be the value of the <code>descriptor</code> field of
+   |command parameters|.
+
+1. Let |state| be the value of the <code>state</code> field of |command
+   parameters|.
+
+1. Let |context id| be the value of the <code>context</code> field of
+   |command parameters|.
+
+1. If |context id| is not present, let |context| be the [=top-level browsing context=]
+   of |session|. Otherwise, let |context| be the result of [=trying=] to
+   [=get a browsing context=] with |context id|.
+
+1. Let |origin| be the value of the <code>origin</code> field of |command
+   parameters| if present, or null otherwise, representing an [=origin=].
+
+TODO: Add intermediate steps for setPermission.
+
+1. Return [=success=] with data null.
+
+</div>
+
 ## The network Module ## {#module-network}
 
 The <dfn export for=modules>network</dfn> module contains commands and events
@@ -9112,7 +9218,7 @@ The [=remote end subscribe steps=], with [=subscribe priority=] 10, given
 
 </div>
 
-## The Input Module ## {#module-input}
+## The input Module ## {#module-input}
 
 The <dfn export for=modules>input</dfn> module contains functionality for
 simulated user input.