From 51bfe92cf8a572daac57d0da40b615e9db32667b Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Thu, 27 Oct 2022 09:17:31 -0700 Subject: [PATCH 1/6] Replace window-placement permission references with window-management. --- index.bs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index fcbf550..00c96ef 100644 --- a/index.bs +++ b/index.bs @@ -502,7 +502,7 @@ The getScreenDetails() method steps are: 1. Run the following steps [=/in parallel=]: - 1. Let |permissionState| be [=/request permission to use=] `"window-placement"`. + 1. Let |permissionState| be [=/request permission to use=] `"window-management"`. 1. If |permissionState| is "{{PermissionState/denied}}" then [=/reject=] |promise| with a {{"NotAllowedError"}} {{DOMException}} and abort these steps. @@ -729,11 +729,11 @@ The {{Element/requestFullscreen|Element.requestFullscreen()}} method steps are u ## Permission API Integration ## {#api-permission-api-integration} -This specification defines a [=/default powerful feature=] that is identified by the [=powerful feature/name=] "window-placement". +This specification defines a [=/default powerful feature=] that is identified by the [=powerful feature/name=] "window-management". The [[permissions]] API provides a uniform way for websites to query the state of their permissions. -Issue: Add {{window-placement}} to [[permissions]] registry. +Issue: Add {{window-management}} to [[permissions]] registry. Issue: Define behavior of cached objects and method steps when the permission is revoked. (See [#80](https://github.com/w3c/window-placement/issues/80)) @@ -741,11 +741,11 @@ Issue: Define behavior of cached objects and method steps when the permission is ## Permission Policy integration ## {#api-permission-policy-integration} -This specification defines a [=/policy-controlled feature=] identified by the string "window-placement". Its [=/default allowlist=] is `"self"`. See [[permissions-policy]] and its list of [Experimental Features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#experimental-features). +This specification defines a [=/policy-controlled feature=] identified by the string "window-management". Its [=/default allowlist=] is `"self"`. See [[permissions-policy]] and its list of [Experimental Features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#experimental-features). Note: A [=/document=]’s permissions policy determines whether any content in that document is allowed to obtain {{ScreenDetails}} or place content on specific screens. If disabled, promises returned by {{Window/getScreenDetails}} will be rejected, and requests to place content on specific screens will be clamped to the [=/current screen=]. -Issue: Move [=permission-policy/window-placement=] to [Proposed](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#proposed-features) or [Standardized](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#proposed-features) feature lists when appropriate. +Issue: Move [=permission-policy/window-management=] to [Proposed](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#proposed-features) or [Standardized](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md#proposed-features) feature lists when appropriate. # Security Considerations # {#security} From 143b7a825b3e852f5f919094164365ada5a4dea4 Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Thu, 27 Oct 2022 09:17:50 -0700 Subject: [PATCH 2/6] Replace window-placement permission references with window-management. --- CHANGES.md | 2 +- EXPLAINER.md | 10 +++++----- EXPLAINER_initiating_multi_screen_experiences.md | 8 ++++---- HOWTO.md | 2 +- security_and_privacy.md | 4 ++-- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index b87468f..6bc11d3 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -17,7 +17,7 @@ aligning related proposals, partly motivating a new Screens interface. - User-friendly screen labels, which vastly improve custom multi-screen picker and configuration UIs for apps - Screen change events, including changes to the multi-screen bit, to obviate polling - Chrome Security requested that this feature be disabled by default on embedded pages via a [permissions policy](https://w3c.github.io/webappsec-permissions-policy/) - - In the second origin trial, cross origin iframes need to specify an `allow="window-placement"` attribute. + - In the second origin trial, cross origin iframes need to specify an `allow="window-management"` attribute. - Some screen properties of reduced imperative were removed, at least for now. - `id`: A temporary generated per-origin unique ID; reset when cookies are deleted. - `touchSupport`: Whether the screen supports touch input; a predecessor of `pointerTypes`. diff --git a/EXPLAINER.md b/EXPLAINER.md index c8aefd4..0cc9803 100644 --- a/EXPLAINER.md +++ b/EXPLAINER.md @@ -64,7 +64,7 @@ of existing window placement APIs to support extended multi-screen environments. * Add `Window.getScreenDetails()` to request additional permission-gated screen info * Add `ScreenDetails` and `ScreenDetailed` interfaces for additional screen info * Standardize common `Screen.availLeft` and `Screen.availTop` attributes - * Add Permission API support for a new `window-placement` entry + * Add Permission API support for a new `window-management` entry These allow web applications to make window placement requests optimized for the specific use case, characteristics of available screens, and user preferences. @@ -524,7 +524,7 @@ window.moveTo(screen.availLeft + offsetX, screen.availTop + offsetY); See prior discussion regarding coordinates in the section titled "Support requests to place web app windows on a specific screen". -### Add Permission API support for a new `window-placement` entry +### Add Permission API support for a new `window-management` entry Sites may wish to know whether users have already granted or denied a requisite permission before attempting to access gated information and capabilities. The @@ -534,7 +534,7 @@ the `query()` method of the [Permission API](https://w3c.github.io/permissions). ```webidl enum PermissionName { // ... - "window-placement", + "window-management", // ... }; ``` @@ -544,7 +544,7 @@ cross-screen support for users that have already granted permission, and respect users that have already denied the permission. ```js -navigator.permissions.query({name:'window-placement'}).then(function(status) { +navigator.permissions.query({name:'window-management'}).then(function(status) { if (status.state === "prompt") showMultiScreenEducationalUI(); else if (status.state === "granted") @@ -561,7 +561,7 @@ If a cross-origin page wants an embedded page to have access to this API, then it needs to specify an `allow` attribute on the iframe, e.g. ```html - + ``` ### Open questions diff --git a/EXPLAINER_initiating_multi_screen_experiences.md b/EXPLAINER_initiating_multi_screen_experiences.md index 8e415d7..ea39e3b 100644 --- a/EXPLAINER_initiating_multi_screen_experiences.md +++ b/EXPLAINER_initiating_multi_screen_experiences.md @@ -61,11 +61,11 @@ fullscreen request and a popup window request from a single user-activation. An eventual end-goal (that is not explored here) is to enable scripts to enter fullscreen on N screens and open M popup windows on M screens from a single user activation, where N and M are disjoint and potentially empty sets, as long as -the site has the multi-screen `window-placement` permission. +the site has the multi-screen `window-management` permission. ## Proposal -Allow sites with the `window-placement` permission to +Allow sites with the `window-management` permission to [place fullscreen content on a specific screen](https://webscreens.github.io/window-placement/#usage-overview-place-fullscreen-content-on-a-specific-screen) *and* [place a new popup window on a separate specific screen](https://webscreens.github.io/window-placement/#usage-overview-place-windows-on-a-specific-screen), @@ -76,7 +76,7 @@ This fulfills the API partner’s use case in the most narrow manner possible, a limits the potential for accidental misuse or abuse with the following set of mitigations: -- Require the window-placement permission and devices with multiple displays +- Require the window-management permission and devices with multiple displays - These are needed to show a popup and fullscreen on separate displays - Allow opening a popup *after* requesting fullscreen on a specific display - This ordering prevents basic misuse (showing a popup under fullscreen) @@ -98,7 +98,7 @@ precedent: requestFullscreen() [waives its activation requirement](https://fullscreen.spec.whatwg.org/#dom-element-requestfullscreen) on user generated orientation changes. -Note: the `window-placement` permission is requested earlier, as needed, by +Note: the `window-management` permission is requested earlier, as needed, by [`Window.getScreenDetails()`](https://w3c.github.io/window-placement/#dom-window-getscreendetails), before scripts can request fullscreen (or open a popup) on a specific screen. So it is expected that scripts making these requests already have permission. diff --git a/HOWTO.md b/HOWTO.md index 73b1cb7..f4e74c2 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -42,7 +42,7 @@ async function main() { ## How to use API enhancements -[Fullscreen Companion Window](https://chromestatus.com/feature/5173162437246976) permits sites with the window-placement permission to [initiate a multi-screen experience](https://github.com/w3c/window-placement/blob/main/EXPLAINER_initiating_multi_screen_experiences.md) from a single user activation. Specifically, this proposed enhancement allows scripts to open a popup window when requesting fullscreen on a specific screen of a multi-screen device. Test this by invoking "Fullscreen slide and open notes" in the [window-placement-demo](https://michaelwasserman.github.io/window-placement-demo). +[Fullscreen Companion Window](https://chromestatus.com/feature/5173162437246976) permits sites with the window-management permission to [initiate a multi-screen experience](https://github.com/w3c/window-placement/blob/main/EXPLAINER_initiating_multi_screen_experiences.md) from a single user activation. Specifically, this proposed enhancement allows scripts to open a popup window when requesting fullscreen on a specific screen of a multi-screen device. Test this by invoking "Fullscreen slide and open notes" in the [window-placement-demo](https://michaelwasserman.github.io/window-placement-demo). - Chrome 104+ enables this enhancement by default. - Chrome 102+ supports this enhancement with this flag enabled: - `chrome --enable-features=WindowPlacementFullscreenCompanionWindow` diff --git a/security_and_privacy.md b/security_and_privacy.md index fbf6258..86ae2b9 100644 --- a/security_and_privacy.md +++ b/security_and_privacy.md @@ -56,7 +56,7 @@ web application's window placement actions, and declarative arrangements specified by a site are unlikely to provide the requisite expressiveness for most use cases. -All newly exposed information could be gated by the proposed `window-placement` +All newly exposed information could be gated by the proposed `window-management` permission, limited to secure contexts, top-level frames, gated by user gesture, active window contexts, and other protections to help mitigate concerns around [fingerprinting](https://w3c.github.io/fingerprinting-guidance). @@ -232,7 +232,7 @@ No. The questionnaire could ask if implementing the proposal would yield or enable any additional Security and Privacy protections. -By adding the proposed `window-placement` permission, browsers could further +By adding the proposed `window-management` permission, browsers could further limit unpermissioned access to existing information and capabilities. For example, without the permission, browsers could: From 5a186b93c29360a6f6ec8e161c163153d7f0d24f Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Fri, 28 Oct 2022 10:54:22 -0700 Subject: [PATCH 3/6] Add note about permission rename. --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index 6bc11d3..6349b15 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -22,6 +22,7 @@ aligning related proposals, partly motivating a new Screens interface. - `id`: A temporary generated per-origin unique ID; reset when cookies are deleted. - `touchSupport`: Whether the screen supports touch input; a predecessor of `pointerTypes`. - `pointerTypes`: The set of PointerTypes supported by the screen. +- The `window-placement` permission and permission policy name were renamed to `window-management` as per GitHub issue [114](https://github.com/w3c/window-placement/issues/114) ## Examples of requesting additional screen information From 1ee0987b91a66844b3e8bf873edced65d594de3a Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Fri, 28 Oct 2022 10:54:37 -0700 Subject: [PATCH 4/6] Add note about permission rename. --- index.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.bs b/index.bs index 00c96ef..98ebb65 100644 --- a/index.bs +++ b/index.bs @@ -733,6 +733,8 @@ This specification defines a [=/default powerful feature=] that is identified by The [[permissions]] API provides a uniform way for websites to query the state of their permissions. +Note: Previously published versions of this document used the permission name "{{window-placement}}". User agents should carefully migrate to the updated permission string: "{{window-management}}". See [#114](https://github.com/w3c/window-placement/issues/114). + Issue: Add {{window-management}} to [[permissions]] registry. Issue: Define behavior of cached objects and method steps when the permission is revoked. (See [#80](https://github.com/w3c/window-placement/issues/80)) From 76ff44645364cb4a347e1a16dcb4bc3585abc057 Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Fri, 28 Oct 2022 11:19:49 -0700 Subject: [PATCH 5/6] Change permission policy items. --- CHANGES.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 6349b15..9361652 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -16,8 +16,7 @@ aligning related proposals, partly motivating a new Screens interface. - Partner feedback requested access to: - User-friendly screen labels, which vastly improve custom multi-screen picker and configuration UIs for apps - Screen change events, including changes to the multi-screen bit, to obviate polling -- Chrome Security requested that this feature be disabled by default on embedded pages via a [permissions policy](https://w3c.github.io/webappsec-permissions-policy/) - - In the second origin trial, cross origin iframes need to specify an `allow="window-management"` attribute. +- Starting in the second origin trial, a [permissions policy](https://w3c.github.io/webappsec-permissions-policy/) was added, so embedders could control feature access of embedded iframes. - Some screen properties of reduced imperative were removed, at least for now. - `id`: A temporary generated per-origin unique ID; reset when cookies are deleted. - `touchSupport`: Whether the screen supports touch input; a predecessor of `pointerTypes`. From d74a0027fe54457a4b8351870b1653d5dd40b7b2 Mon Sep 17 00:00:00 2001 From: Brad Triebwasser Date: Thu, 1 Dec 2022 13:07:53 -0800 Subject: [PATCH 6/6] Add rename explainer. --- EXPLAINER_spec_and_permission_rename.md | 78 +++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 EXPLAINER_spec_and_permission_rename.md diff --git a/EXPLAINER_spec_and_permission_rename.md b/EXPLAINER_spec_and_permission_rename.md new file mode 100644 index 0000000..0b48159 --- /dev/null +++ b/EXPLAINER_spec_and_permission_rename.md @@ -0,0 +1,78 @@ +## Window Placement Spec & Permission Rename +## Background +The Multi-Screen Window Placement [spec](https://w3c.github.io/window-placement/) has primarily utilized the terminology "Window Placement" ever since it was initially drafted in 2020. This includes the title of the spec, the spec short name (`window-placement`), and user-facing API components like [permission](https://w3c.github.io/window-placement/#api-permission-api-integration) and permission [policy](https://w3c.github.io/window-placement/#api-permission-policy-integration) descriptors which gate the API. + +## Problem +The existing "Window Placement" terminology only describes one specific component of the API that allows web applications to [place browser windows on target displays](https://w3c.github.io/window-placement/#api-window-attribute-and-method-definition-changes). It doesn't encompass the entire surface of the API described in the spec, nor will it adequately describe potential future additions to the API. + +## Goals +Use more generalized wording that encapsulates more of the current API functionality and provides better futureproofing of the API. Specifically, rename all instances of "Window Placement" terminology with "Window Management". This includes: +* Repository names and [URLs](https://github.com/w3c/window-placement) +* [Spec](https://w3c.github.io/window-placement) titles, short names and URLs +* Spec definitions: [permission](https://w3c.github.io/window-placement/#api-permission-api-integration) and permission [policy](https://w3c.github.io/window-placement/#api-permission-policy-integration) descriptors + * Specifically "`window-placement`" will become "`window-management`" +* Other spec text and descriptions +* [Web Platform Tests](https://github.com/web-platform-tests/wpt/tree/master/window-placement) and resulting [URLs](https://wpt.live/window-placement/) + +## Breaking Changes +A majority of the rename should not be disruptive and URL redirections will be used wherever possible. However renaming the permission and permission policy descriptors require careful migration efforts since they are user-facing strings which are in use by web applications. The following sections provide illustrative examples of what web developers will be required to update. The timeframe of these changes are browser specific; chromium's tentative schedule is outlined in [User Agent API Migration](#user-agent-api-migration) + +### Permission Descriptor +Web applications that query the permission name to obtain permission to use the API will need to update: + +**From:** +```js +navigator.permissions.query({name:'window-placement'}) +``` + +**To:** +```js +navigator.permissions.query({name:'window-management'}) +``` +### Permission Policy +Web applications utilizing the [iframe allow attribute](https://w3c.github.io/webappsec-permissions-policy/#iframe-allow-attribute) to control this feature will need to update: + +**From:** +```html + +``` + +**To:** +```html + +``` +Web servers utilizing the "[Permissions-Policy](https://w3c.github.io/webappsec-permissions-policy/#permissions-policy-http-header-field)" header to control this feature will need to update: + +**From:** +``` +Permission-Policy: window-placement 'self' +``` + +**To:** +``` +Permission-Policy: window-management 'self' +``` + +## Migration Plan +More details on the migration efforts shall be posted and tracked in [Issue #114](https://github.com/w3c/window-placement/issues/114). The following sections provide a high level overview of the migration plan. + + +### User Agent API Migration +User agents are expected to do their own due diligence in carefully migrating user-facing descriptors. However, a general approach is described below and is the plan Chromium will follow: +1. Add the new descriptor strings "`window-management`" which act as an alias to the old descriptors "`window-placement`", gated behind a browser flag to enable or disable the new aliases. + * Additionally, the browser should log a console deprecation warning when the old aliases are used by a web application. + * Chromium ETA: Q4 2022 +2. Slowly roll out the new alias across users and track metrics on usage of the old vs. new alias. + * Chromium ETA: Q4 2022 +3. Add a browser flag which removes the old alias. + * Chromium ETA: Q1 2023 +4. Slowly roll out the removal of the old alias. + * Chromium ETA: Q2 2023 + +### Spec and Repository +Migration of the repository and spec literature will occur slowly as needed. At a high level, the following will occur or may have already occurred: +* Rename the permission and permission policy strings in the spec. +* Update the permission registry with the new permission name. +* Rename the title of the spec +* Rename the spec repository, and create redirections from the old URL. +* Rename the published spec short name and create redirections from the old URL(s). \ No newline at end of file