Clipboard API and events

Table of Contents

• 1. Conformance
• 2. Introduction
• 3. Use Cases
• 4. Events
  • 4.1 copy event
  • 4.2 cut event
  • 4.3 paste event
• 5. Clipboard event interface
  • 5.1 Attributes
  • 5.2 Methods
  • 5.3 Determining the target property for clipboard events
• 6. DataTransfer interface
  • 6.1 Attributes
  • 6.2 Methods
• 7. Interaction with other events
  • 7.1 Event listeners that modify selection or focus
• 8. Pasting data with multiple parts
• 9. Security and privacy considerations
• 10. Cross-origin copy/paste of source code
• A. References
  • A.1 Normative references
  • A.2 Informative references

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

2. Introduction

This section is informative

This specification defines the common clipboard operations of cutting, copying and pasting, in such a way that they are exposed to Web Applications and can be adapted to provide advanced functionalities. Its goal is to provide for compatibility where possible with existing implementations.

3. Use Cases

This section is informative

There are many use cases for being able to change the default clipboard operations (cut/copy/paste). We have collected a few samples to demonstrate possible uses, although these may not all be supported by this specification.

Rich content editing

When copying text which contains hyperlinks or other structure, it is often useful to be able to reformat the content to preserve important information.

Graphics with built-in semantics

In order to make web applications which allow the manipulation of rich text, or of graphic content such as SVG, it is useful to provide a mechanism that allows for copying more than just the rendered content.

Mathematical information

With content such as mathematics, simply copying rendered text and pasting it into another application generally leads to most of the semantics being lost. MathML often needs to be transformed to be copied as plain text, for example to make sure "to the power of" is shown with the caret "^" sign. Also, the XML source could be placed in the clipboard with the appropriate transformation occurring when pasting.

4. Events

5. Clipboard event interface

The ClipboardEvent interface extends the Event interface [DOMEVENTS].

A synthetic paste event must not give a script access to data on the real system clipboard. Synthetic cut and copy events must not modify data on the system clipboard.

interface ClipboardEvent : Event {
    readonly attribute DataTransfer clipboardData;
    void initClipboardEvent (in DOMString eventType, in boolean canBubble, in boolean cancelable, in DOMString dataType, in DOMString data);
};

6. DataTransfer interface

This section is informative. The normative specification for the DataTransfer interface is found in [HTML5]'s Drag and Drop section.

TODO: review/sync with DataTransfer. There will be a very brief informative (not normative) text below for each method, clearly indicating that the normative stuff is in the HTML5 spec. We will however maintain tests for this, so keeping in sync with HTML5 will remain important.

interface clipboardData : DataTransfer {
    attribute DataTransferItems items;
    attribute DOMStringList     types;
    DOMString getData (in DOMString type);
    boolean   setData (in DOMString type, in DOMString data);
    boolean   clearData ([Optional] in DOMString type);
};

7. Interaction with other events

If the clipboard operation is triggered by keyboard input, the implementation must fire the corresponding event as the default action of the keydown event that initiates the clipboard operation. For example, if the user presses Ctrl-C to copy, dispatching a copy event must be the default action of the C key's keydown event. The event is asyncronous but must be dispatched before keyup events for the relevant keys.

The default action of the cut and paste events may cause the implementation to dispatch other supported events, such as textInput, input, change, validation events, DOMCharacterDataModified and DOMNodeRemoved / DOMNodeInserted. Any such events are queued up to fire after processing of the cut/paste event is finished.

The implementation must not dispatch other input-related events like textInput, input, change, and validation events in response to the copy operation.

8. Pasting data with multiple parts

This section needs to be more specific on how different types of data should be handled. We probably need to specify different algorithms for exposing data types as "drag data store" entries, and set up some kind of registry mapping the various data types (both MIME types and platform-specific type identifiers) to various algorithms.

Security precautions

Risks

This section is informative.

There are two security risks associated with pasting formatted or multi-part data.

• The user might paste hidden data which the user is not aware of. This may happen if, for example, the markup includes <input type="hidden"> tags or HTML comments. Such hidden data might contain sensitive information.
• The implementation might grant scripts access to local files the user did not intend to expose.

To determine what policies to use, the factors we consider are

• The origin of the data being pasted
• The origin of data sub-parts such as referenced images
• The origin of the running script

Security policies

The implementation must not download referenced online resources and expose their contents in the FileList.

Should we allow this for same-origin copy/paste content? There is no strong use case for doing so, since pasting markup which references online content should "just work" in the sense that referenced content should affect the rendering without the script having direct access to it.

If the data on the clipboard is not from a local application, the implementation must not give access to any referenced local files.

If the data originates from a web site, and the origin of the web site and the origin of the document associated with the script that created the event listener differs, the implementation should apply the sanitization algorithm before exposing HTML data.

For example, if the data contains <img src="file://localhost/example.jpg"> but the data's origin is an online resource, the implementation must not expose the content of example.jpg as an entry in the files attribute.

Using clipboardData.files list for multi-part paste

Some formats may contain multiple parts and embed images or other forms of data. Implementations must handle data with sub-parts by populating the FileList files attribute of the DataTransfer interface. References to sub-parts must be replaced by content-id references using the cid: URL scheme [RFC2392]. The identifier of each sub-part is its index in the FileList.

For example, if the user pastes some HTML that contains one IMG tag linking to an image on the local hard drive, a compliant implementation would add a File item to the files list, and modify the SRC attribute of the IMG tag to read src="cid:0" to reference the 0^th file in the filelist.

9. Security and privacy considerations

Enabling authors to change what is copied by a user, or to make an automated copy of something that was never selected and allowing unrestricted calls to paste information can raise various security and privacy concerns.

An example scenario of a problem is where a user selects a link and copies it, but a different link is copied to the clipboard. The effect of this can range from an unexpected result on pasting to an attempted "phishing" attack.

Privacy concerns

Untrusted scripts should not get uncontrolled access to a user's clipboard data. This specification assumes that granting access to the current clipboard data when a user explicitly initiates a paste operation from the UA's trusted chrome is acceptable. However, implementors must proceed carefully, and as a minimum implement the precautions below:

• Objects implementing the DataTransfer interface to return clipboard data must not be available outside the ClipboardEvent event handler.
• If a script stores a reference to an object implementing the DataTransfer interface to use from outside the ClipboardEvent event handler, all methods must be no-ops when called outside the expected context
• Implementations must not let scripts create synthetic clipboard events to get access to real clipboard data

Implementations may choose to further limit the functionality provided by the DataTransfer interface. For example, an implementation may allow the user to disable this API, or configure which web sites should be granted access to it.

Nuisance considerations

Scripts may use the DataTransfer API to annoy and confuse users by altering the data on the system clipboard from copy and cut events. This specification does not attempt to prevent such nuisances, though implementations may add additional restrictions.

Implementations must handle scripts that try to place excessive amounts of data on the clipboard gracefully.

10. Cross-origin copy/paste of source code

How do we safeguard cross-origin copy/paste of source code? Are below rules sufficient to prevent sneaky cross-site request forgery attacks?

Pasting HTML and other markup-based content copied from one site into another site might compromise the security of the former site, for example by giving the second site access to passwords, nonces and other sensitive data that might be embedded in the markup.

If a script calls getData('text/html'), the implementation supports pasting HTML, and the data available on the clipboard is from a different origin, the implementation must sanitize the content by following these steps:

1. Parse the code on the clipboard to a DOM tree
2. Remove all of the following elements: SCRIPT, APPLET, OBJECT, FORM, INPUT, BUTTON, TEXTAREA, SELECT, OPTION, OPTGROUP and comment nodes. For all mentioned elements except FORM, also remove all child nodes.
3. Remove any elements whose computed style's display property is 'none'
4. Remove all event handler attributes from all elements
5. Remove all data- attributes from all elements
6. If the implementation supports embedding javascript: URLs or other forms of scripting inside CSS instructions, such scripts must be removed.
7. Remove HTML comments.
8. Serialize the DOM and return the generated string to the script

Implementations may let the user indicate that an app is trusted to not attack other apps and apply its own safety measures, thus bypass the above algorithm. Implementations may also implement additional restrictions, for example only support text/plain if the user does a cross-origin paste, or only support text/plain if content from an encrypted origin is pasted into a non-encrypted page.