diff --git a/images/out-of-scope-ux.png b/images/out-of-scope-ux.png new file mode 100644 index 0000000..de08128 Binary files /dev/null and b/images/out-of-scope-ux.png differ diff --git a/images/scope-privacy-info.png b/images/scope-privacy-info.png new file mode 100644 index 0000000..d807907 Binary files /dev/null and b/images/scope-privacy-info.png differ diff --git a/scope_extensions-explainer.md b/scope_extensions-explainer.md index 9f7ea3b..bfc38b9 100644 --- a/scope_extensions-explainer.md +++ b/scope_extensions-explainer.md @@ -7,6 +7,26 @@ web apps to extend their [scope](https://www.w3.org/TR/appmanifest/#understanding-scope) to other origins. +## Introduction + +A web application's content might originate from different scopes. Currently, if +an installed web application navigates to a url that is out of the scope defined +in the manifest file, a security UX will appear in the form of a bar to indicate +to the user that they are outside of the defined scope of the application. See +figure below. + +![Installed web app showing out-of-scope UX](images/out-of-scope-ux.png) + +The app in the image (`PWinter`) has navigated to a url out of its scope +(`airhorner.com`). The white bar on top of the web app is providing information +to the user about this change of scope. While this is a security feature, it can +be the case that an application wants to extend its scope. For example, an +application might host content that is located in one specific origin, and rely +on a login page that is out of the scope of the application itself to access +that content. In other cases, the same application might be associated to +multiple Top Level Domains, that might respond to different locales +(`app.com`, `app.co.uk`, `app.co.cr`, etc). + ## Use Cases / Goals @@ -107,9 +127,9 @@ A URL is in the extended scope of a web app if both: ### Link capturing from another origin If an origin A adds a web app B to its `web-app-origin-association` file, A is -implicitly authorizing app B to intercept navigations to URLs in A. This -implies that app B can potentially spoof origin A and therefore it is advised -that origin A and web app B should be owned by the same entity. +implicitly authorizing app B to intercept navigations to URLs in A. This implies +that app B can potentially spoof origin A and therefore it is advised that +origin A and web app B should be owned by the same entity. User agents may perform link capturing for user navigations within a web app's extended scope and launch the web app instead of performing the navigation. @@ -136,12 +156,12 @@ the following attack vector: ## Future extensions -- More specific scoping e.g. scope suffix or include/exclude lists or - [URL patterns](https://wicg.github.io/urlpattern/). - - To be able to apply these more specific scoping rules to the primary - scope (including exclusion). - One possible approach is to have the primary origin specified in the - `scope_extensions` list and have it override the behaviour of `scope`. +- More specific scoping e.g. scope suffix or include/exclude lists or [URL + patterns](https://wicg.github.io/urlpattern/). + - To be able to apply these more specific scoping rules to the primary scope + (including exclusion). One possible approach is to have the primary origin + specified in the `scope_extensions` list and have it override the behaviour + of `scope`. - Replace the constraint on manifest URLs that are bound by scope (except for `start_url`) to instead be bound by the extended scope. Validation of the associated origins is not required for these URLs to be part of a valid @@ -160,13 +180,33 @@ the following attack vector: the web app to [capture navigations][link-capturing-from-another-origin] into the associated origin. +### Extended Scope Permissions + +When an application uses `scope_extensions` to expand its scope, **each +additional scope's permissions remain the same**. Expanding scopes does not +imply any change in permissions. The only thing that changes after being +included in a scope is that the security UX will not appear when an app +navigates to content served from those scopes. + +### Additional security UX + +For added security when in the installed web application, the app might display +UX that always displays the current scope that is being served, along with +privacy and permission settings of that specific scope. + +![Current scope being displayed on the privacy menu of installed web +app](images/scope-privacy-info.png) + +In the previous image, a user can always see which domain is serving content +under the privacy menu. + ## Related Proposals ### [URL Handlers][url-handlers] -The Scope Extensions proposal is intended to be a replacement for the -[URL Handlers][url-handlers] proposal with the following changes: +The Scope Extensions proposal is intended to be a replacement for the [URL +Handlers][url-handlers] proposal with the following changes: - Re-orient the goal to be focused just on expanding the set of origins/URLs in the web app's scope. Remove the goal of registering web apps as URL handlers in the user's operating system. That behaviour will be covered by individual @@ -175,8 +215,8 @@ The Scope Extensions proposal is intended to be a replacement for the - Rename the new manifest field from `url_handlers` to `scope_extensions` to reflect the change in goals. - Move the association file from "/web-app-origin-association.json" to - "/.well-known/web-app-origin-association". This better conforms - with [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615). + "/.well-known/web-app-origin-association". This better conforms with + [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615). - Change the association file entries to be keyed on the [web app identifier](manifest-identity) rather than the web app's manifest URL (the former having been added to the Manifest spec in the interim).