Updates scope-extensions explainer (#104)

Adds clarification details for scope extensions security & permissions implications.

Co-authored-by: Lu <[email protected]>

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 "<origin>/web-app-origin-association.json" to
-   "<origin>/.well-known/web-app-origin-association". This better conforms
-   with [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615).
+   "<origin>/.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).