Add threats and required mitigations to privacy-security-explainer.md

This is not fully filled out yet, and needs additional review to ensure
it is aligned with #638

privacy-security-explainer.md

@@ -8,7 +8,7 @@ In the context of XR, sensitive information includes, but is not limited to, use
 # Protection types
 WebXR must be structured to ensure end users are protected from developers gathering and using sensitive information inappropriately. The necessary protections will vary based on the sensitive data being guarded, and, in some cases, more than one protection is necessary to adequately address the potential threats exposed by specific sensitive information.
 
-## Documents and origins
+## Trustworthy documents and origins
 When sensitive information can be exposed, the requesting document must be:
 * [Responsible](https://html.spec.whatwg.org/multipage/webappapis.html#responsible-document)
 * Of a [secure context](https://w3c.github.io/webappsec-secure-contexts/#secure-contexts)
@@ -22,6 +22,8 @@ When sensitive information can be exposed, the requesting document must be:
 
 ### Feature policy
 **TODO** Fill this in with what is agreed upon in [#308](https://github.com/immersive-web/webxr/issues/308), [#729](https://github.com/immersive-web/webxr/issues/729), [#730](https://github.com/immersive-web/webxr/issues/730), and [#731](https://github.com/immersive-web/webxr/issues/731).
+#### Underlying sensors feature policy
+In addition to the WebXR specific feature policy, feature policies for underlying sensors must also be respected if a site could isolate and extract sensor data that would otherwise be blocked by those feature policies. WebXR must not be a 'back door' for accessing data that is otherwise prevented.
 
 ## Trusted UI
 **TODO** Fill this in with what is agreed upon in [#718](https://github.com/immersive-web/webxr/issues/718) and [#719](https://github.com/immersive-web/webxr/issues/719).
@@ -57,9 +59,175 @@ Rounding, quantization, and fuzzing are three categories of mitigations that mod
 Limiting is when data is reported only when it is within a specific range. For example, it is possible to comfortably limit reporting positional pose data when a user has moved beyond a specific distance away from an approved location. Care should be taken to ensure that the user experience is not negatively affected when employing this mitigation. It is often desireable to avoid a 'hard stop' at the at the end of a range as this may cause disruptive user experiences.
 
 # Protected functionality
+The sensitive information exposed via WebXR can be divided into categories that share threat profiles and the protections necessary to mitigate those threats.
+
 **TODO** Fill this in based on the information in [#638](https://github.com/immersive-web/webxr/pull/638) so that it adequately addresses [#393](https://github.com/immersive-web/webxr/issues/393) and [#485](https://github.com/immersive-web/webxr/issues/485).
 
-# Appendix A: Proposed IDL
-```webidl
-// TODO: Add any necessary IDL
-```
+## Immersiveness
+Users must be in control of when immersive sessions are created because the creation causes invasive changes on a user's machine. For example, it will engage the XR device sensors, take over access to the device's display, and begin presentation which may terminate another application's access to the XR hardware. It may also incur significant power or performance overhead on some systems or trigger the launching of a status tray or storefront.
+
+Developers indicate the desire to create an immersive session by passing `immersive-vr` or `immersive-ar` into `xr.requestSession()`. 
+
+```js
+// VR button click handler
+function onVRClick() {
+  xr.requestSession('immersive-vr').then(onVRSessionCreated);
+}
+
+//AR button click handler
+function onARClick() {
+  xr.requestSession('immersive-ar').then(onARSessionCreated);
+}
+```
+
+In response, the UA must ensure that:
+* The function was invoked in response to a [user activation](#user-activation)
+* The request originates from a [trustworthy document and origin](#trustworthy-documents-and-origins)
+* The request originates from a document that is [visible and has focus](#visibility-and-focus)
+* The request originates from a document allowed to use the WebXR [feature policy](#feature-policy) as well as the [underlying sensors' feature policies](#underlying-sensors-feature-policies)
+* User intention is well understood, either via [explicit consent](#explicit-consent) or [implicit consent](#implict-consent)
+
+If these requirements are not met, the promise returned from `requestSession()` must reject.
+
+## Spatial relationships
+Users must be in control of when poses derived from spatial relationships are made available to developers. This control is divided into several subcategories.
+**TODO** explain what's extra scary about this data
+
+### Unbounded reference spaces
+Developers indicate the desire for unbounded viewer tracking at the time of session creation by adding `unbounded` to either `XRSessionInit.requiredFeatures` or `XRSessionInit.optionalFeatures`. 
+
+```js
+function onARClick() {
+  xr.requestSession('immersive-ar', { requiredFeatures: ['unbounded'] } )
+  .then(onARSessionCreated);
+}
+```
+
+In response the UA must ensure that:
+* The document is allowed to use all the policy-controlled features associated with the sensor types used to track the native origin of an unbounded reference space
+* User intention is well understood, either via [explicit consent](#explicit-consent) or [implicit consent](#implict-consent)
+* The XR device is capable of unbounded tracking
+
+If these requirements are not met and `unbounded` is listed in `XRSessionInit.requiredFeatures` then the promise returned from `requestSession()` must be rejected. Otherwise, the promise may be fulfilled but future calls to `XRSession.requestReferenceSpace()` must fail when passed `unbounded`.
+
+### Bounded reference spaces
+Developers indicate the desire for bounded viewer tracking at the time of session creation by adding `bounded-floor` to either `XRSessionInit.requiredFeatures` or `XRSessionInit.optionalFeatures`. 
+
+```js
+function onVRClick() {
+  xr.requestSession('immersive-vr', { requiredFeatures: ['bounded-floor'] } )
+  .then(onVRSessionCreated);
+}
+
+xr.requestSession('inline', { optionalFeatures: ['bounded-floor'] } )
+  .then(onInlineSessionCreated);
+}
+```
+
+In response, the UA must ensure that:
+* The document is allowed to use all the policy-controlled features associated with the sensor types used to track the native origin of a bounded reference space
+* User intention is well understood, either via [explicit consent](#explicit-consent) or [implicit consent](#implict-consent)
+* The device is capable of bounded tracking
+
+If these requirements are not met and `bounded-floor` is listed in `XRSessionInit.requiredFeatures` then the promise returned from `requestSession()` must be rejected. Otherwise, the promise may be fulfilled but future calls to `XRSession.requestReferenceSpace()` must fail when passed `bounded-floor`.
+
+Once a session is created, developers may attempt to create a bounded reference space by passing `bounded-floor` into `XRSession.requestReferenceSpace()`.
+
+```js
+let xrReferenceSpace;
+function onSessionCreated(session) {
+  session.requestReferenceSpace('bounded-floor')
+  .then((referenceSpace) => { xrReferenceSpace = referenceSpace; })
+  .catch( (e) => { /* handle gracefully */ } );
+}
+```
+
+In response, the UA must ensure that: 
+* Bounded reference spaces are allowed to be created based on the restrictions above
+* Any group of `local`, `local-floor`, and `bounded-floor` reference spaces that are capable of being related to one another must share a common native origin; this restriction does not apply when `unbounded` reference spaces are also permitted to be created
+* `XRBoundedReferenceSpace.boundsGeometry` must be [rounded](#rounding) sufficiently to prevent fingerprinting; rounding to the nearest 5cm is suggested
+* The region represented by the rounded bounds geometry must be a subset of the original bounds
+* If the floor level is based on sensor data or is set to a non-default emulated value, the `y` value of the native origin must be [rounded](#rounding) sufficiently to prevent fingerprinting; rounding to the nearest 1cm is suggested
+
+If these requirements are not met, the promise returned from `XRSession.requestReferenceSpace()` must be rejected.
+
+### Local and local-floor reference spaces
+When creating an `inline` session, developers indicate the desire for local viewer tracking at the time of session creation by adding `local` and/or `local-floor` to either `XRSessionInit.requiredFeatures` or `XRSessionInit.optionalFeatures`. Creating an `immersive-vr` or `immersive-ar` session adds `local` and `local-floor` to `XRSessionInit.requiredFeatures` implicitly.
+
+```js
+function onVRClick() {
+  xr.requestSession('immersive-vr', { requiredFeatures: ['local-floor'] } )
+  .then(onVRSessionCreated);
+}
+
+xr.requestSession('inline', { optionalFeatures: ['local'] } )
+  .then(onInlineSessionCreated);
+}
+```
+
+In response, the UA must ensure that:
+* The document is allowed to use all the policy-controlled features associated with the sensor types used to track the native origin of a bounded reference space
+* User intention is well understood, either via [explicit consent](#explicit-consent) or [implicit consent](#implict-consent)
+* The device is capable of local tracking
+
+If these requirements are not met for either an `immersive-vr` or an `immersive-ar` session, the promise returned from `requestSession()` must be rejected.  If these requirements are not met for an `inline` session in which `local` or `local-floor` is listed in `XRSessionInit.requiredFeatures` then the promise returned from `requestSession()` must be rejected. Otherwise, the promise may be fulfilled but future calls to `XRSession.requestReferenceSpace()` must fail when passed `local` or `local-floor`.
+
+Once a session is created, developers may attempt to create local reference spaces by passing either `local` or `local-floor` into `XRSession.requestReferenceSpace()`.
+
+```js
+let xrReferenceSpace;
+function onSessionCreated(session) {
+  session.requestReferenceSpace('local-floor')
+  .then((referenceSpace) => { xrReferenceSpace = referenceSpace; })
+  .catch( (e) => { /* handle gracefully */ } );
+}
+```
+
+In response, the UA must ensure that: 
+* Bounded reference spaces are allowed to be created based on the restrictions above
+* Any group of `local`, `local-floor`, and `bounded-floor` reference spaces that are capable of being related to one another must share a common native origin; this restriction does not apply when `unbounded` reference spaces are also permitted to be created
+* If the floor level is based on sensor data or is set to a non-default emulated value, the `y` value of the native origin must be [rounded](#rounding) sufficiently to prevent fingerprinting; rounding to the nearest 1cm is suggested
+
+If these requirements are not met, the promise returned from `XRSession.requestReferenceSpace()` must be rejected.
+
+### Pose data
+Developers indicate the desire for `XRPose` data by calling `XRFrame.getPose()`.
+
+```js
+function onSessionRafCallback(XRFrame frame) {
+    let motionControllerPose = frame.getPose(xrSession.inputSources[0], xrReferenceSpace);
+}
+```
+
+Before returning poses based on sensor data, the UA must ensure that:
+* The session's document is [visible and has focus](#visibility-and-focus)
+* The `XRSession.visibility` is set to `visible` 
+* **TODO** address issues [#696](https://github.com/immersive-web/webxr/issues/696) and [#724](https://github.com/immersive-web/webxr/issues/724)
+* All `XRPose` and `XRViewerPose` 6DOF pose data computed using a `local` or `local-floor` reference space is [limited](#limiting) to a reasonable distance from the reference space's native origin; the suggested default distance is 15 meters in each direction
+* All `XRPose` and `XRViewerPose` 6DOF pose data computed using a `bounded-floor` reference space must be [limited](#limiting) to a reasonable distance beyond the `boundsGeometry` in all directions; the suggested distance is 1 meter beyond the bounds in all directions
+
+### Viewer pose data
+Developers indicate the desire for `XRViewerPose` data by calling `XRFrame.getViewerPose()`.
+
+```js
+function onSessionRafCallback(XRFrame frame) {
+    let viewerPose = frame.getViewerPose(xrReferenceSpace);
+}
+```
+
+In addition to the restrictions on returning [pose data](#pose-data), the UA must ensure that:
+* **TODO** This whole section is still unfinished
+* May be the result of an XRSessionMode of `immersive-vr` or `immersive-ar`. In the future this may also be caused an XRReferenceSpaceFeature of `diorama` which could result in an `inline` session needing to request user consent at `requestReferenceSpace()`.
+* **TODO** determine if there's actually a difference in threat between a cave system, one with multiple views, and one with a user configured IPD?
+* User consent is required before creating an XRSession on a device with configurable interpupillary distance (IPD), if subsequent calls to XRFrame.getViewerPose() will return XRView.transforms that can be used to compute the configured IPD.
+* User consent must have been obtained on devices with configurable interpupillary distance before creating an XRViewerPose that will return an XRView for each eye.
+* If the device supports configurable or factory-calibrated interpupillary distance that may vary from device to device, then the XRView transform data must be rounded to prevent fingerprinting. Specific precision for rounding is at the discretion of the user agent.
+* If the XRViewerPose will include multiple XRViews for displays whose positions and orientations have been configured by the user (e.g. in a CAVE) then the XRView transform data must be rounded to prevent fingerprinting.
+* User Consent at `requestSession()` and rounding
+
+## Stuff that still needs a home in this document
+Under what circumstances would consent not be required since its required even for orientation-based tracking?
+* If an input to getPose includes data generated by sensors, at least one of the following conditions must be met to mitigate sensor fingerprinting threats; the user agent may choose the approach that provides the best user experience:
+  * User consent must have been obtained, or
+  * Any transform data generated by sensors must be quantized to prevent sensor fingerprinting, or
+  * The user agent must otherwise ensure that the underlying device sensors are not susceptible to sensor fingerprinting.