User Interface Security and the Visibility API

4. Content Security Policy Interface

This section describes the Content Security Policy directive introduced in this specification to provide declarative configuration of protection against input when an element does not meet it’s visibility requirements.

The optional directive-value allows configuration of conditions for which violations will be triggered.

4.1. The input-protection Directive

directive-name    = 'input-protection'
directive-value   = ['area-threshold=' num-val]
                    ['protected-element=' id-selector]
                    ['time-threshold=' num-val]
                    ['visible-margin=' num-val 'px' *3(',' num-val 'px')]

4.1.1. Directive Value

area-threshold A violation will be triggered if an event is delivered to the protected-element or one of its ancestors if the visibility of the protected area is below this threshold.

Threshold values must be in the range [0, 1.0] and represent a percentage of the area as specified by protected-element.getBoundingClientRect(), adjusted by visible-margin. Unlike the imperative API, only a single value may be specified.

protected-element A DOMString used as the argument to getElementById() to resolve the Element to which the policy applies.

If unspecified the policy is applied to the resource’s Document node.

time-threshold A numeric value in the range [0, 10000] that specifies how long, in milliseconds, the screen area containing the protected-element must have unmodified viewiability properties when an event is delivered to it or one of its ancestors.

If not specified, it defaults to 800. If a value outside of the range stated above is given, it defaults ot the nearest value between the lower and higher bounds.

visible-margin Same as visibleMargin.

If unspecified, it defaults to "0px".

5. Processing Model

5.1. Internal Slot Definitions

5.1.1. Browsing Contexts

5.1.2. Element

5.1.3. Document

5.1.4. VisibilityObserver

• [[QueuedEntries]] which is initialized to an empty list
• [[previousVisibleRatio]] which is initialized to 0
• [[previousGlobalViewportPosition]]

• [[callback]]
• [[areaThreshold]]
• [[displacementAware]]
• [[visibleMargin]]
• [[observedElement]] which is initialized to the Document Element if not set in the VisibilityObserverInit dictionary

• [[timeThreshold]]
• [[associatedContentSecurityPolicy]]

5.2. Algorithms

5.2.1. Queue a VisibilityObserver Task

1. If unit’s VisibilityObserverTaskQueued flag is set to true, return.
2. Set unit’s VisibilityObserverTaskQueued flag to true.
3. Post a task to notify visibility observers, or enqueue a task to notify visibility observers in the list of idle request callbacks with an appropriate timeout.

   Should we define an appropriate timeout?

5.2.2. Notify VisibilityObservers

1. Set unit’s VisibilityObserverTaskQueued flag to false.
2. For each Document document in unit
   1. Let notify list be a copy of document’s [[RegisteredVisibilityObservers]] list.
   2. For each VisibilityObserver object observer in notify list, run these steps:
      1. If observer’s internal [[QueuedEntries]] slot is empty, continue.
      2. Let queue be a copy of observer’s internal [[QueuedEntries]] slot.
      3. Clear observer’s internal [[QueuedEntries]] slot.
      4. Invoke callback with queue as the first argument and observer as the second argument and callback this value. If this throws an exception, report the exception.

5.2.3. Queue a VisibilityObserverEntry

1. Append entry to observer’s internal [[QueuedEntries]] slot.
2. Queue a visibility observer task for unit.

5.2.4. Promote Observed GraphicsLayers

This section is non-normative.

Generally, at some point in the rendering of a set of documents in nested browsing contexts into the fully composed graphical representation in the global viewport, a user agent will arrive at a set of intermediate representations we will designate as GraphicsLayers, each of which represents a graphical surface to be painted / clipped / scrolled.

A GraphicsLayer representing the contents of a document in an iframe will be arranged in the layer stack such that at a later phase in the rendering it is automatically clipped and positioned relative to the series of viewports above it, and also subject to being drawn over or transformed by the layers above it.

To prevent potentially malicious composition, the user agent can promote observed graphicsLayers by manipulating them such that a document with [[RegisteredVisibilityObservers]]

• Is clipped and positioned as-if-unmodified within the set of viewports of its ancestor browsing contexts. A promoted document should not be able to occupy more screen real estate than it is given by its embedding contexts.
• Responds to hit testing and events as-if-unmodified. Implementation-specific modifications to internal representations of the document should not change the behavior of the DOM.
• Is not subject to being drawn over or transformed by any other GraphicsLayers, except other promoted layers, which should be treated as fully opaque occlusions when reporting the visibility state of the document.

To promote observed graphicsLayers, given a time now, and an initially empty list promotedLayers, run these steps during the rendering loop at the stage where the intermediate representation of a set of Documents is a set of GraphicsLayers graphicsLayers.

1. For each graphicsLayer in graphicsLayers
2. For each Document document with an intermediate representation in graphicsLayer
   1. If document has an empty list of [[RegisteredVisibilityObservers]], continue.
   2. If document has a non-empty list of [[RegisteredVisibilityObservers]]
      1. If document is not the only Document represented in graphicsLayer, apply whatever implementation-specific steps are necessary to place it in its own layer. (e.g. apply translatez(0) to the documentElement) Let graphicsLayer be that new layer.
   3. Let rectToRaise be the value of document.getBoundingClientRect().
   4. Intersect rectToRaise with document’s viewport clip rect.
   5. For every parent browsing context parent between document and the top-level document, intersect rectToRaise with parent’s viewport clip rect, and finally with the global viewport clip rect.
   6. Clip graphicsLayer to rectToRaise. (graphicsLayer may have zero width and height if it is scrolled off screen by an ancestor browsing context)
   7. Intersect rectToRaise with any items in the promotedLayers list.
   8. Add rectToRaise to the promotedLayers list.
   9. Without reordering prior intermediate representations in a manner which would change event dispatching, hit testing, or the DOM as exposed to JavaScript, reorder the GraphicsLayers such that rectToRaise is on top of the root GraphicsLayer. (e.g. by making it a direct child of the root layer) but beneath any layers in promotedLayers that clipped it.
   10. Let protectedRect be the value of observer’s [[observedElement]].getBoundingClientRect(), adjusted by [[visibleMargin]].
   11. Let visibleRatio be the intersection of protectedRect with rectToRaise, divided by protectedRect if protectedRect is non-zero, and 0 otherwise.
   12. For each of document’s [[RegisteredVisibilityObservers]] observer
       1. Let threshold be the index of the first entry in observer’s internal [[areaThreshold]] slot whose value is greater than or equal to visibleRatio. If visibleRatio is equal to 0, let threshold be -1.
       2. Let oldVisibleRatio be set to observer’s internal [[previousVisibleRatio]] slot.
       3. Let oldThreshold be the index of the first entry in observer’s internal [[areaThreshold]] slot whose value is greater than or equal to oldVisibleRatio. If oldVisibleRatio is equal to 0, let oldThreshold be -1.
       4. Let oldPosition be the value of the observer’s internal [[previousGlobalViewportPosition]].
       5. If threshold does not equal oldThreshold, or if observer’s internal [[displacementAware]] slot is true and oldPosition is not equal to protectedRect,
          • queue a VisibilityObserverEntry
          • Assign visibleRatio to observer’s internal [[previousVisibleRatio]] slot.
          • Assign protectedRect to the value of the observer’s internal [[previousGlobalViewportPosition]] slot.

find exact terms to make sure that we have viewport definitions minus scrollbars

need to also clip to any other layers that were promoted ahead of us!

if a parent and child layer both request to be promoted, the parent’s clipping window will have a complex geometry with holes in it that is not accounted for by this algorithm. Likely need to specify that graphics layers be processed by order of depth.

5.2.5. Enforce An input-protection Directive

1. Parse the policy according to [CSP2].
2. If a value is set for protected-element, let protectedElement be the Element returned by invoking document.getElementById() with the value as the input, or document if null or unset.
3. If document’s [[InputProtectionRequested]] flag is false, set it to true.
4. Construct a new VisibilityObserver observer, with [[areaThreshold]] set to the value of area-threshold, [[visibleMargin]] set to the value of visible-margin, [[observedElement]] set to protectedElement, [[displacementAware]] set to true, and [[callback]] set to a new function with an empty function body.
5. Set the internal [[timeThreshold]] slot of observer to the value of time-threshold
6. Set the internal [[associatedContentSecurityPolicy]] slot of observer to a reference to the Content Security Policy which the input-protection directive is associated with.
7. When dispatching events, when an Element element will handle an Event event, if event is of type Mouse Event, Pointer Event, Drag-and-Drop, or Clipboard Event, (TODO:linkify) and if element has [[InputProtectionObservers]] observers:
   1. If applicable, check the computed style for the cursor. If a cursor is typically displayed but has been hidden or changed to a non-standard bitmap, handle a violation for event and each observer in observers.
   2. Otherwise, for each observer in observers:
      1. If observer’s [[previousVisibleRatio]] is less than [[areaThreshold]], handle a violation for observer.
      2. If observer’s [[previousVisibleRatio]] is greater than [[areaThreshold]], get the most recent VisibilityObserverEntry entry from observer’s [[QueuedEntries]]. If the difference between entry.time and now is less than [[timeThreshold]], handle a violation for observer.

5.2.6. Handle a Violation

• Follow the steps in [CSP2] to report a violation for observer’s [[associatedContentSecurityPolicy]] policy.
• Determine if policy is being enforced or monitored. [CSP2]
• If policy is being enforced, set event’s cancelled flag and stop propagation flag.
• If policy is being monitored, set event.isUnsafe to true.

5.3. External Spec Integrations

5.3.1. HTML Processing Model: Event Loop

5.3.2. DOM: Dispatching Events

5.3.3. isUnsafe Attribute

partial interface Event {
  readonly attribute boolean isUnsafe;
};

isUnsafe, of type boolean, readonly

Will be set to true if the event fired when the event did not meet the document’s input-protection requirements.

6. Privacy Considerations

This section is non-normative.

The timing of visibilityEvents may leak some information across Origin boundaries. An embedded document might have previously been unable to learn that it was obscured, or the timing and nature of repositioning of ancestor frame’s viewports. In some circumstances, this information leak might have privacy implications, but the granularity and nature of the information is such that it should not be of much value to attackers. Compared to anti-clickjacking strategies which rely on pixel comparisions, the side channels exposed by comparing rectulangar masks are very low bandwidth. The privacy gains from preventing clickjacking, considered in a holistic system context, may be quite large.

7. Security Considerations

This section is non-normative.

UI Redressing and Clickjacking attacks rely on violating the contextual and temporal integrity of embedded content. Because these attacks target the subjective perception of the user and not well-defined security boundaries, the heuristic protections afforded by the input-protection directive can never be 100% effective for every interface. It provides no protection against certain classes of attacks, such as displaying content around an embedded resource that appears to extend a trusted dialog but provides misleading information.

When used as a mechanism to report visibility for purposes of monetizing content, operators should be aware that a malicious or modified user agent can always report perfect visibility for content it colludes with. Determining, through remote measurement, whether an ostensible viewer of monetizable content is using an agent which faithfully implements and reports in conformance with this specification is out of scope for this document.

8. Accessibility Considerations

Users of accessibility tools MUST NOT be prevented from accessing content because of input-protection or VisibilityEvents. If a user agent’s interaction modality is not subject to UI redressing attacks or definitions of "visibility" do not apply, the user agent SHOULD report a VisibilityEvent indicating 100% visibility, and SHOULD never fire a violation for any input-protection policy.