Abstract

ThePush API enables sending of apush message to a web application via apush service. Anapplication server can send apush message at any time, even when a web application oruser agent is inactive. Thepush service ensures reliable and efficient delivery to theuser agent.Push messages are delivered to aService Worker that runs in the origin of the web application, which can use the information in the message to update local state or display a notification to the user.

This specification is designed for use with theweb push protocol, which describes how anapplication server oruser agent interacts with apush service.

Status of This Document

This section describes the status of this document at the time of its publication. A list of currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.

This document was published by theWeb Applications Working Group as a Working Draft using theRecommendation track.

Publication as a Working Draft does not imply endorsement byW3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under theW3C Patent Policy.W3C maintains apublic list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.

This document is governed by the03 November 2023W3C Process Document.

This section is non-normative.

The Push API allows a web application to communicate with auser agent asynchronously. This allows anapplication server to provide theuser agent with time-sensitive information whenever that information becomes known, rather than waiting for a user to open the web application.

As defined here,push services support delivery ofpush messages at any time.

In particular, apush message will be delivered to the web application even if that web application is not currently active in a browser window: this relates to use cases in which the user may close the web application, but still benefits from the web application being able to be restarted when apush message is received. For example, apush message might be used to inform the user of an incoming WebRTC call.

Apush message can also be sent when theuser agent is temporarily offline. In support of this, thepush service stores messages for theuser agent until theuser agent becomes available. This supports use cases where a web application learns of changes that occur while a user is offline and ensures that theuser agent can be provided with relevant information in a timely fashion.Push messages are stored by thepush service until theuser agent becomes reachable and the message can be delivered.

The Push API will also ensure reliable delivery of push messages while auser agent is actively using a web application, for instance if a user is actively using the web application or the web application is in active communication with anapplication server through an active worker, frame, or background window. This is not the primary use case for the Push API. A web application might choose to use the Push API for infrequent messages to avoid having to maintain constant communications with theapplication server.

Push messaging is best suited to occasions where there is not already an active communications channel established between theuser agent and the web application. Sendingpush messages requires considerably more resources when compared with more direct methods of communication such as theFetch API or [WebSockets].Push messages usually have higher latency than direct communications and they can also be subject to restrictions on use. Mostpush services limit the size and quantity ofpush messages that can be sent.

Theweb push protocol [RFC8030] describes a protocol that enables communication between auser agent orapplication server and apush service. Alternative protocols could be used in place of this protocol, but this specification assumes the use of this protocol; alternative protocols are expected to provide compatible semantics.

TheContent-Encoding HTTP header, described in Section 3.1.2.2 of [RFC7231], indicates the content coding applied to the payload of apush message.

The contents of apush message are encrypted [RFC8291]. However, thepush service is still exposed to the metadata of messages sent by anapplication server to auser agent over apush subscription. This includes the timing, frequency and size of messages. Other than changingpush services, which user agents may disallow, the only known mitigation is to increase the apparent message size by padding.

There is no guarantee that apush message was sent by anapplication server having the same origin as the web application. Theapplication server is able to share the details necessary to use apush subscription with a third party at its own discretion.

The following requirements are intended to protect the privacy and security of the user as far as possible, and subject to meeting that goal, to protect the integrity of theapplication server's communication with the user.

User agentsMUST NOT provide Push API access to web applications without theexpress permission of the user.User agentsMUST acquire consent for permission through a user interface for each call to thesubscribe() method, unless a previous permission grant has been persisted, or a prearranged trust relationship applies. Permissions that are preserved beyond the current browsing sessionMUST be revocable.

The Push API may have to wake up the Service Worker associated with theservice worker registration in order to run the developer-provided event handlers. This can cause resource usage, such as network traffic, that theuser agentSHOULD attribute to the web application that created thepush subscription.

Theuser agentMAY consider thePushSubscriptionOptions when acquiring permission or determining the permission status.

When a permission is revoked, theuser agentMAYfire the "pushsubscriptionchange" event for subscriptions created with that permission, with theservice worker registration associated with thepush subscription asregistration, aPushSubscription instance representing thepush subscription asoldSubscription, andnull asnewSubscription. Theuser agentMUSTdeactivate the affected subscriptions in parallel.

When aservice worker registration is unregistered, any associatedpush subscriptionMUST bedeactivated.

Thepush endpointMUST NOT expose information about the user to be derived by actors other than thepush service, such as the user's device, identity or location. See the Privacy Considerations in [RFC8030] for the exact requirements.

Thepush endpoint of adeactivatedpush subscriptionMUST NOT be reused for a newpush subscription. This prevents the creation of a persistent identifier that the user cannot remove. This also prevents reuse of the details of onepush subscription to sendpush messages to anotherpush subscription.

User agentsMUST implement the Push API to only be available in asecure context. This provides better protection for the user against man-in-the-middle attacks intended to obtain push subscription data. Browsers may ignore this rule for development purposes only.

This section is non-normative.

Apush message is sent from anapplication server to a web application as follows:

• theapplication server requests that thepush service deliver apush message using the [RFC8030]. This request uses thepush endpoint included in thepush subscription;
• thepush service delivers the message to a specificuser agent, identifying thepush endpoint in the message;
• theuser agent identifies the intendedService Worker and activates it as necessary, and delivers thepush message to theService Worker.

This overall framework allowsapplication servers to activate aService Worker in response to events at theapplication server. Information about those events can be included in thepush message, which allows the web application to react appropriately to those events, potentially without needing to initiate network requests.

The following code and diagram illustrate a hypothetical use of the push API.

// https://example.com/serviceworker.jsthis.onpush =event => {console.log(event.data);// From here we can write the data to IndexedDB, send it to any open// windows, display a notification, etc.}// https://example.com/webapp.js// inside an async function...try {const serviceWorkerRegistration =await navigator.serviceWorker.register("serviceworker.js"  );const pushSubscription =await serviceWorkerRegistration.pushManager.subscribe();// The push subscription details needed by the application// server are now available, and can be sent to it using,// for example, an XMLHttpRequest.console.log(pushSubscription.endpoint);console.log(pushSubscription.getKey("p256dh"));console.log(pushSubscription.getKey("auth"));}catch (err) {// In a production environment it might make sense to// also report information about errors back to the// application server.console.log(error);}

5.2 Sequence diagram

This section is non-normative.

The Service Worker specification defines aServiceWorkerRegistration interface [SERVICE-WORKERS], which this specification extends.

WebIDL[SecureContext]partial interfaceServiceWorkerRegistration {  readonly attributePushManagerpushManager;};

ThepushManager attribute exposes aPushManager, which has an associatedservice worker registration represented by theServiceWorkerRegistration on which the attribute is exposed.

ThePushManager interface defines the operations to accesspush services.

WebIDL[Exposed=(Window,Worker),SecureContext]interfacePushManager {  [SameObject] static readonly attributeFrozenArray<DOMString>supportedContentEncodings;Promise<PushSubscription>subscribe(optionalPushSubscriptionOptionsInitoptions = {});Promise<PushSubscription?>getSubscription();Promise<PermissionState>permissionState(optionalPushSubscriptionOptionsInitoptions = {});};

ThesupportedContentEncodings attribute exposes the sequence of supported content codings that can be used to encrypt the payload of apush message. A content coding is indicated using theContent-Encoding header field when requesting the sending of apush message from thepush service.

User agentsMUST support theaes128gcm content coding defined in [RFC8291], andMAY support content codings defined in previous versions of the draft for compatibility reasons.

WebIDL[Exposed=(Window,Worker),SecureContext]interfacePushSubscriptionOptions {  readonly attributebooleanuserVisibleOnly;  [SameObject] readonly attributeArrayBuffer?applicationServerKey;};

WebIDLdictionaryPushSubscriptionOptionsInit {booleanuserVisibleOnly = false;  (BufferSource orDOMString)?applicationServerKey = null;};

APushSubscription object represents apush subscription.

WebIDL[Exposed=(Window,Worker),SecureContext]interfacePushSubscription {  readonly attributeUSVStringendpoint;  readonly attributeEpochTimeStamp?expirationTime;  [SameObject] readonly attributePushSubscriptionOptionsoptions;ArrayBuffer?getKey(PushEncryptionKeyNamename);Promise<boolean>unsubscribe();PushSubscriptionJSONtoJSON();};dictionaryPushSubscriptionJSON {USVStringendpoint;EpochTimeStamp?expirationTime = null;record<DOMString,USVString>keys;};

Whengetting theendpoint attribute, theuser agentMUST return thepush endpoint associated with thepush subscription. Theuser agentMUST use a serialization method that does not contain input-dependent branches (that is, one that is constant time).

Whengetting theexpirationTime attribute, theuser agentMUST return thesubscription expiration time associated with thepush subscription if there is one, ornull otherwise.

When getting theoptions attribute, theuser agentMUST return aPushSubscriptionOptions object representing the options associated with thepush subscription.

ThegetKey() method retrieves keying material that can be used for encrypting and authenticating messages. WhengetKey() is invoked the following process is followed:

1. Find the internal slot corresponding to the key named by thename argument.
2. If a slot was not found, returnnull.
3. Initialize a variablekey with a newly instantiatedArrayBuffer instance.
4. If the internal slot contains an asymmetric key pair, set the contents ofkey to the serialized value of the public key from the key pair. This uses the serialization format described in the specification that defines the name. For example, [RFC8291] specifies that the "p256dh" public key is encoded using the uncompressed format defined in [ANSI-X9-62] Annex A (that is, a 65 octet sequence that starts with a 0x04 octet).
5. Otherwise, if the internal slot contains a symmetric key, set the contents ofkey to a copy of the value from the internal slot. For example, theauth parameter contains an octet sequence used by theuser agent to authenticate messages sent by anapplication server.
6. Returnkey.

Keys named "p256dh" and "auth"MUST be supported, and their valuesMUST correspond to those necessary for the user agent to decrypt received push messages in accordance with [RFC8291].

Theunsubscribe() method when invokedMUST run the following steps:

1. Letpromise bea new promise.
2. Returnpromise and continue the following steps asynchronously.
3. If thepush subscription has already beendeactivated, resolvepromise withfalse and terminate these steps.
4. Run the following step in parallel:
   1. Deactivate thepush subscription. Theuser agentMUST NOT deliver any furtherpush messages for thepush subscription.

      If theuser agent failed to request thepush service todeactivate thepush subscription, for example because of network failures, itSHOULD retry the request to thepush service for a reasonable amount of time.

5. Resolvepromise withtrue.

ThetoJSON() method when invokedMUST run the following steps:

1. Letjson be a newPushSubscriptionJSON dictionary.
2. Setjson["endpoint"] to the result ofgetting theendpoint attribute ofthis.
3. Setjson["expirationTime"] to the result ofgetting theexpirationTime attribute ofthis.
4. Letkeys be a new empty instance ofrecord<DOMString, USVString> .
5. For each identifieri corresponding to keys in internal slots on thePushSubscription, ordered by the name of the key:
   1. If the internal slot corresponds to an asymmetric key pair, letb be the encoded value of the public key corresponding to the key namei, using the encoding defined for the key name (seegetKey()).
   2. Otherwise, letb be the value as returned bygetKey.
   3. Lets be the URL-safe base64 encoding without padding [RFC4648] ofb as aUSVString. Theuser agentMUST use a serialization method that does not branch based on the value ofb.
   4. Setkeys[i] tos.
6. Setjson["keys"] tokeys.
7. Returnjson.

APushSubscriptionJSON dictionary represents theJSON type of aPushSubscription. In ECMAScript this can be converted into a JSON string through theJSON.stringify() function.

Thekeys record contains an entry for each of the supportedPushEncryptionKeyName entries to the URL-safe base64 encoded representation [RFC4648] of its value.

Note that the options to aPushSubscription are not serialized.

WebIDLenumPushEncryptionKeyName {"p256dh","auth"};

WebIDL[Exposed=ServiceWorker,SecureContext]interfacePushMessageData {ArrayBufferarrayBuffer();Blobblob();Uint8Arraybytes();anyjson();USVStringtext();};

PushMessageData objects have an associatedbytes (abyte sequence), which is set on creation.

ThearrayBuffer() method steps are to return anArrayBuffer whose contents arethis'sbytes. Exceptions thrown during the creation of theArrayBuffer object are re-thrown.

Theblob() method steps are to return a newBlob object whose contents arethis'sbytes.

Thebytes() method steps are to return a newUint8Array backed by aArrayBuffer whose contents arethis'sbytes. Exceptions thrown during the creation of theArrayBuffer object are re-thrown.

Thejson() method steps are to return the result ofparsing JSON bytes to a JavaScript value giventhis'sbytes.

Thetext() method steps are to return the result of runningUTF-8 decode onthis'sbytes.

Toextract a byte sequence fromobject, run these steps:

1. Letbytes be an empty byte sequence.
2. Switch onobject's type:

   BufferSource

   Setbytes to a copy ofobject's contents.

   USVString

   Setbytes to the result of runningutf-8 encode onobject.

3. Returnbytes.

ThePush API does not provide any means itself to present data it receives from apush service. Instead, thePush API relies on other APIs – primarily theNotifications API Standard – to present received information to an end user. As such, there are no accessibility requirements for thePush API itself. However, specifications such as [NOTIFICATIONS] provide guidance how to present notifications in an accessible manner.

Further, presenting an accessible interface might depend on transferring more information than a push message can convey. Push messages are best suited to carrying small amounts of content or identifiers. Any larger resources need to be fetched from servers.

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 wordsMAY,MUST,MUST NOT,SHOULD, andSHOULD NOT in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria that apply to a single product: theuser agent that implements the interfaces that it contains.

WebIDLdictionaryPushPermissionDescriptor :PermissionDescriptor {booleanuserVisibleOnly = false;};[SecureContext]partial interfaceServiceWorkerRegistration {  readonly attributePushManagerpushManager;};[Exposed=(Window,Worker),SecureContext]interfacePushManager {  [SameObject] static readonly attributeFrozenArray<DOMString>supportedContentEncodings;Promise<PushSubscription>subscribe(optionalPushSubscriptionOptionsInitoptions = {});Promise<PushSubscription?>getSubscription();Promise<PermissionState>permissionState(optionalPushSubscriptionOptionsInitoptions = {});};[Exposed=(Window,Worker),SecureContext]interfacePushSubscriptionOptions {  readonly attributebooleanuserVisibleOnly;  [SameObject] readonly attributeArrayBuffer?applicationServerKey;};dictionaryPushSubscriptionOptionsInit {booleanuserVisibleOnly = false;  (BufferSource orDOMString)?applicationServerKey = null;};[Exposed=(Window,Worker),SecureContext]interfacePushSubscription {  readonly attributeUSVStringendpoint;  readonly attributeEpochTimeStamp?expirationTime;  [SameObject] readonly attributePushSubscriptionOptionsoptions;ArrayBuffer?getKey(PushEncryptionKeyNamename);Promise<boolean>unsubscribe();PushSubscriptionJSONtoJSON();};dictionaryPushSubscriptionJSON {USVStringendpoint;EpochTimeStamp?expirationTime = null;record<DOMString,USVString>keys;};enumPushEncryptionKeyName {"p256dh","auth"};[Exposed=ServiceWorker,SecureContext]interfacePushMessageData {ArrayBufferarrayBuffer();Blobblob();Uint8Arraybytes();anyjson();USVStringtext();};[Exposed=ServiceWorker,SecureContext]partial interfaceServiceWorkerGlobalScope {  attributeEventHandleronpush;  attributeEventHandleronpushsubscriptionchange;};[Exposed=ServiceWorker,SecureContext]interfacePushEvent :ExtendableEvent {constructor(DOMStringtype, optionalPushEventIniteventInitDict = {});  readonly attributePushMessageData?data;};typedef (BufferSource orUSVString)PushMessageDataInit;dictionaryPushEventInit :ExtendableEventInit {PushMessageDataInitdata;};[Exposed=ServiceWorker,SecureContext]interfacePushSubscriptionChangeEvent :ExtendableEvent {constructor(DOMStringtype, optionalPushSubscriptionChangeEventIniteventInitDict = {});  readonly attributePushSubscription?newSubscription;  readonly attributePushSubscription?oldSubscription;};dictionaryPushSubscriptionChangeEventInit :ExtendableEventInit {PushSubscriptionnewSubscription = null;PushSubscriptionoldSubscription = null;};

The editors would like to express their gratitude to the Mozilla and Telefónica Digital teams implementing the Firefox OS Push message solution, as well as to the following people who provided significant technical input to this document: Antonio Amaya, Miguel García Arribas, Ben Bangert, Kit Cambridge, José Manuel Cantera, JR Conlin, Albert Crespell, Matt Gaunt, Phil Jenvey, Guillermo López, Nikhil Marathe, John Mellor, Pınar Özlen, Fernando R. Sela, Shijun Sun and Doug Turner.