From dcf28f680a55666cdaf899cd56f5655da0f2025d Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Mon, 30 Oct 2023 15:11:26 -0700 Subject: [PATCH 01/10] Add `unsanitized` option to async clipboard API. --- index.bs | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 23d0f45..9e68bd7 100644 --- a/index.bs +++ b/index.bs @@ -782,11 +782,15 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; [SecureContext, Exposed=Window] interface Clipboard : EventTarget { - Promise<ClipboardItems> read(); + Promise<ClipboardItems> read(optional ClipboardUnsanitizedFormats formats = {}); Promise<DOMString> readText(); Promise<undefined> write(ClipboardItems data); Promise<undefined> writeText(DOMString data); }; + + dictionary ClipboardUnsanitizedFormats { + sequence<DOMString> unsanitized; + }; Some methods of the {{Clipboard}} interface take or return multiple {{ClipboardItem}} objects. However, not all platforms support more than one [=/clipboard item=]; on such platforms, the algorithms below will ignore any {{ClipboardItem}} objects beyond the first one that are passed to {{Clipboard/write()}}, and {{Clipboard/read()}} and {{Clipboard/readText()}} only get one clipboard item from the OS. @@ -798,17 +802,33 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; {{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].

+ An unsanitized object is a [=sequence=] of {{DOMString}} corresponding to the [=representation/mime type=]. + +

+ Only "text/html" MIME type is supported for [=unsanitized=] object. In the future, other MIME types may be added. +

+ The clipboard task source is triggered in response to reading or writing of [=system clipboard data=].

read()

- The {{Clipboard/read()}} method must run these steps: + The {{Clipboard/read(formats)}} method must run these steps: 1. Let |realm| be [=this=]'s [=relevant realm=]. 1. Let |p| be [=a new promise=] in |realm|. + 1. Let |format| be a {{DOMString}}. + + 1. If |formats| is not empty, then: + + 1. If |formats|'s size is greater than 1, then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. + + 1. Set |format| to |formats|[0]. + + 1. If |format| is not "text/html", then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. + 1. Run the following steps [=in parallel=]: 1. Let |r| be the result of running [=check clipboard read permission=]. @@ -841,7 +861,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; Issue: It should be possible to read the data asynchronously from the system clipboard after the author calls getType, however, this set of steps implies that data will be provided at the time of read. - 1. The user agent, MAY sanitize |representation|'s [=representation/data=], unless |representation|'s [=representation/MIME type=]'s essence is "image/png", which should remain unsanitized to preserve meta data. + 1. The user agent, MAY sanitize |representation|'s [=representation/data=], unless |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is "image/png", which should remain unsanitized to preserve meta data, or equal to |format| if |format| is not empty. 1. Append |representation| to |item|'s [=list of representations=]. From e8c1a9bee865acb4011e06a72286317be525e4f7 Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Tue, 31 Oct 2023 14:04:18 -0700 Subject: [PATCH 02/10] Address PR comments. --- index.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 9e68bd7..b344562 100644 --- a/index.bs +++ b/index.bs @@ -802,17 +802,17 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; {{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].

- An unsanitized object is a [=sequence=] of {{DOMString}} corresponding to the [=representation/mime type=]. + An unsanitized object is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=]. It contains unsanitized mime types that is currently limited to "text/html".

- Only "text/html" MIME type is supported for [=unsanitized=] object. In the future, other MIME types may be added. + In the future, other MIME types may be added.

The clipboard task source is triggered in response to reading or writing of [=system clipboard data=].
-

read()

+

read(|formats|)

The {{Clipboard/read(formats)}} method must run these steps: 1. Let |realm| be [=this=]'s [=relevant realm=]. @@ -827,7 +827,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. Set |format| to |formats|[0]. - 1. If |format| is not "text/html", then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. + 1. If |format| is not [=unsanitized mime types=], then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. 1. Run the following steps [=in parallel=]: From 26100d7b4b5cd04e44f6d3d6b6d296884290fe2a Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Tue, 31 Oct 2023 14:30:23 -0700 Subject: [PATCH 03/10] Address PR comments. --- index.bs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index b344562..7ae4a26 100644 --- a/index.bs +++ b/index.bs @@ -827,7 +827,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. Set |format| to |formats|[0]. - 1. If |format| is not [=unsanitized mime types=], then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. + 1. If |format| is not in [=unsanitized mime types=], then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. 1. Run the following steps [=in parallel=]: @@ -861,7 +861,11 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; Issue: It should be possible to read the data asynchronously from the system clipboard after the author calls getType, however, this set of steps implies that data will be provided at the time of read. - 1. The user agent, MAY sanitize |representation|'s [=representation/data=], unless |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is "image/png", which should remain unsanitized to preserve meta data, or equal to |format| if |format| is not empty. + 1. The user agent, MAY sanitize |representation|'s [=representation/data=], unless it satisfies the below conditions: + + 1. |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is "image/png", which should remain unsanitized to preserve meta data. + + 1. If |format| is not empty and |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is equal to |format|. 1. Append |representation| to |item|'s [=list of representations=]. From ddb5503836e2c070963935e3c4350a2ed0ad4aec Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Thu, 9 Nov 2023 16:11:55 -0800 Subject: [PATCH 04/10] Address PR comments. --- index.bs | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index 7ae4a26..0f74511 100644 --- a/index.bs +++ b/index.bs @@ -542,6 +542,19 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; * Custom format [=string/starts with=] `"web "`("web" followed by U+0020 SPACE) prefix and suffix (after stripping out `"web "`) passes the [=parsing a MIME type=] check. +

Unsanitized data types

+ + The implementation MAY recognize the native OS clipboard format description + for the following data types, to be able to populate the + {{ClipboardItem}} with the correct description for paste events, and + set the correct data format on the OS clipboard in response to copy and cut + events. + + These data types must not be sanitized and should be exposed by UAs + if a corresponding native type exists on the clipboard: + + * text/html +

Asynchronous Clipboard API

@@ -620,6 +633,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; Some platforms may support having more than one [=/clipboard item=] at a time on the [=clipboard=], while other platforms replace the previous [=/clipboard item=] with the new one. A [=/clipboard item=] has a list of representations, each representation with an associated mime type (a [=/MIME type=]), an isCustom flag, initially |false|, that indicates if this [=representation=] should be treated as a [=web custom format=] (as opposed to a well-known format of the [=system clipboard=]), and data (a {{ClipboardItemData}}). + A web custom format has [=representation/isCustom=] set to |true|.

@@ -802,11 +816,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; {{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].

- An unsanitized object is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=]. It contains unsanitized mime types that is currently limited to "text/html". - -

- In the future, other MIME types may be added. -

+ {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that are in the [=unsanitized data types=]. The clipboard task source is triggered in response to reading or writing of [=system clipboard data=]. @@ -819,15 +829,11 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. Let |p| be [=a new promise=] in |realm|. - 1. Let |format| be a {{DOMString}}. - 1. If |formats| is not empty, then: - 1. If |formats|'s size is greater than 1, then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. + 1. For each |format| in |formats|["{{ClipboardUnsanitizedFormats/unsanitized}}"]: - 1. Set |format| to |formats|[0]. - - 1. If |format| is not in [=unsanitized mime types=], then [=reject=] |p| with {{"NotAllowedError"}} {{DOMException}} in |realm|. + 1. If |format| is not in [=unsanitized data types=], then [=reject=] |p| with |format| {{"NotAllowedError"}} {{DOMException}} in |realm|. 1. Run the following steps [=in parallel=]: @@ -857,15 +863,23 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. Set |representation|'s [=representation/MIME type=] to |mimeType|. + 1. Let |isUnsanitized| be |false|. + + 1. If |formats| is not empty, then: + + 1. For each |format| in |formats|["{{ClipboardUnsanitizedFormats/unsanitized}}"]: + + 1. If |format| is equal to [=representation/MIME type=], set |isUnsanitized| to true. + 1. Set |representation|'s [=representation/data=] to |systemClipboardRepresentation|'s [=system clipboard representation/data=]. Issue: It should be possible to read the data asynchronously from the system clipboard after the author calls getType, however, this set of steps implies that data will be provided at the time of read. - 1. The user agent, MAY sanitize |representation|'s [=representation/data=], unless it satisfies the below conditions: + 1. The user agent, MUST NOT sanitize |representation|'s [=representation/data=], if it satisfies the below conditions: 1. |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is "image/png", which should remain unsanitized to preserve meta data. - 1. If |format| is not empty and |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is equal to |format|. + 1. |isUnsanitized| is true. 1. Append |representation| to |item|'s [=list of representations=]. From 9da00db36649e2fff28e85a8bfbef12a1c881ab4 Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Wed, 15 Nov 2023 11:39:44 -0800 Subject: [PATCH 05/10] Addressed PR comments. --- index.bs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 0f74511..9f31929 100644 --- a/index.bs +++ b/index.bs @@ -546,7 +546,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; The implementation MAY recognize the native OS clipboard format description for the following data types, to be able to populate the - {{ClipboardItem}} with the correct description for paste events, and + {{ClipboardItem}} with the correct [=/MIME type=], and set the correct data format on the OS clipboard in response to copy and cut events. @@ -882,6 +882,8 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. |isUnsanitized| is true. 1. Append |representation| to |item|'s [=list of representations=]. + + 1. Set |isUnsanitized| to |false|. 1. If |item|'s [=list of representations=] size is greater than 0, append |item| to |items|. From ad4077bab6600fbb3a232823b8974532f3a0619c Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Wed, 15 Nov 2023 16:04:40 -0800 Subject: [PATCH 06/10] Addressed PR comments. --- index.bs | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index 9f31929..a99201e 100644 --- a/index.bs +++ b/index.bs @@ -544,17 +544,9 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn;

Unsanitized data types

- The implementation MAY recognize the native OS clipboard format description - for the following data types, to be able to populate the - {{ClipboardItem}} with the correct [=/MIME type=], and - set the correct data format on the OS clipboard in response to copy and cut - events. - - These data types must not be sanitized and should be exposed by UAs - if a corresponding native type exists on the clipboard: - - * text/html + These data types MUST NOT be sanitized by UAs: + * image/png (which should remain unsanitized to preserve meta data)

Asynchronous Clipboard API

@@ -816,7 +808,11 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; {{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].

- {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that are in the [=unsanitized data types=]. + Optional unsanitized data types are [=representation/mime type=]s that MUST not be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: + + * text/html + + {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that are [=optional unsanitized data types=]. The clipboard task source is triggered in response to reading or writing of [=system clipboard data=]. @@ -833,7 +829,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. For each |format| in |formats|["{{ClipboardUnsanitizedFormats/unsanitized}}"]: - 1. If |format| is not in [=unsanitized data types=], then [=reject=] |p| with |format| {{"NotAllowedError"}} {{DOMException}} in |realm|. + 1. If |format| is not in [=optional unsanitized data types=], then [=reject=] |p| with |format| {{"NotAllowedError"}} {{DOMException}} in |realm|. 1. Run the following steps [=in parallel=]: @@ -877,7 +873,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; 1. The user agent, MUST NOT sanitize |representation|'s [=representation/data=], if it satisfies the below conditions: - 1. |representation|'s [=representation/MIME type=]'s [=MIME type/essence=] is "image/png", which should remain unsanitized to preserve meta data. + 1. |representation|'s [=representation/MIME type=] is in [=unsanitized data types=] list. 1. |isUnsanitized| is true. From 4211ab2fbd1f0569bcdf248a6c0e22cc3ffb554b Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Thu, 16 Nov 2023 14:37:42 -0800 Subject: [PATCH 07/10] Addressed comments. --- index.bs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index a99201e..6b3886d 100644 --- a/index.bs +++ b/index.bs @@ -546,7 +546,11 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; These data types MUST NOT be sanitized by UAs: - * image/png (which should remain unsanitized to preserve meta data) + * image/png + +

+ The image/png MIME type is not sanitized to preserve meta data. +

Asynchronous Clipboard API

@@ -808,12 +812,11 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; {{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].

- Optional unsanitized data types are [=representation/mime type=]s that MUST not be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: + {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that are [=optional unsanitized data types=]. + Optional unsanitized data types are [=representation/mime type=]s that MUST NOT be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: * text/html - {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that are [=optional unsanitized data types=]. - The clipboard task source is triggered in response to reading or writing of [=system clipboard data=].
From f96a21c9fd9600febd3ca7114ed698c39ae8644f Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Fri, 17 Nov 2023 17:04:04 -0800 Subject: [PATCH 08/10] Address comments. --- index.bs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 6b3886d..cb57f78 100644 --- a/index.bs +++ b/index.bs @@ -548,6 +548,8 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; * image/png + * [=optional unsanitized data types=] +

The image/png MIME type is not sanitized to preserve meta data.

@@ -812,7 +814,7 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; {{Clipboard/read()}} returns a {{Promise}} to [=clipboard items=] object that represents contents of [=system clipboard data=].

- {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that are [=optional unsanitized data types=]. + {{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that the author wants to be treated as [=optional unsanitized data types=]. Optional unsanitized data types are [=representation/mime type=]s that MUST NOT be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: * text/html From 9e5e1b7c24258930d642602becdf0f642ea65bb3 Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Fri, 17 Nov 2023 17:16:29 -0800 Subject: [PATCH 09/10] Address comments. --- index.bs | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/index.bs b/index.bs index cb57f78..907e46b 100644 --- a/index.bs +++ b/index.bs @@ -550,9 +550,9 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; * [=optional unsanitized data types=] -

- The image/png MIME type is not sanitized to preserve meta data. -

+ Optional unsanitized data types are [=representation/mime type=]s that MUST NOT be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: + + * text/html

Asynchronous Clipboard API

@@ -815,9 +815,6 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn;

{{ClipboardUnsanitizedFormats/unsanitized}} is a [=sequence=] of {{DOMString}}s corresponding to the [=representation/mime type=] that the author wants to be treated as [=optional unsanitized data types=]. - Optional unsanitized data types are [=representation/mime type=]s that MUST NOT be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: - - * text/html The clipboard task source is triggered in response to reading or writing of [=system clipboard data=]. From 0312e3e0f3906645c4c6e6aa8da5184cd2e6b6d2 Mon Sep 17 00:00:00 2001 From: Anupam Snigdha Date: Fri, 17 Nov 2023 17:28:53 -0800 Subject: [PATCH 10/10] Add clarification. --- index.bs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 907e46b..e322d5b 100644 --- a/index.bs +++ b/index.bs @@ -550,7 +550,8 @@ url: https://w3c.github.io/permissions/#permissions-task-source; type: dfn; * [=optional unsanitized data types=] - Optional unsanitized data types are [=representation/mime type=]s that MUST NOT be sanitized by the user agent. The valid [=optional unsanitized data types=] are listed below: + Optional unsanitized data types are [=representation/mime type=]s specified by the web authors that MUST NOT be sanitized by the user agent. + The valid [=optional unsanitized data types=] are listed below: * text/html