Push API

2. 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 MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

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

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL].

3. Dependencies

The terms current settings object, event handler, event handler event type, fire a simple event, queue a task and trusted event are defined in [HTML51].

Promise, JSON.parse and JSON.stringify are defined in [ECMASCRIPT].

EventInit, DOMException, AbortError, InvalidStateError, InvalidAccessError, InvalidCharacterError, SecurityError, event listener, and steps for constructing events are defined in [DOM].

The terms service worker, service worker registration, installing worker, waiting worker, and active worker, and the types ServiceWorkerRegistration, ServiceWorkerGlobalScope, ExtendableEvent, ExtendableEventInit, extend lifetime promises, the Clear Registration algorithm, and the Handle Functional Event algorithm are defined in [SERVICE-WORKERS].

The term secure context is defined in [POWERFUL-FEATURES].

The algorithms utf-8 encode, and utf-8 decode are defined in [ENCODING].

Blob is defined in [FILEAPI].

Any, ArrayBuffer, BufferSource, DOMString, DOMTimeStamp, JSON type, NotAllowedError, NotSupportedError, USVString and get the underlying value are defined in [WEBIDL].

The web push protocol [RFC8030] describes a protocol that enables communication between a user agent or application server and a push 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.

The Content-Encoding HTTP header, described in Section 3.1.2.2 of [RFC7231], indicates the content coding applied to the payload of a push message.

4. Concepts

5. Security and privacy considerations

User agents MUST NOT provide Push API access to webapps without the express permission of the user. User agents MUST acquire consent for permission through a user interface for each call to the subscribe() method, unless a previous permission grant has been persisted, or a prearranged trust relationship applies. Permissions that are preserved beyond the current browsing session MUST be revocable.

The Push API may have to wake up the Service Worker associated with the service worker registration in order to run the developer-provided event handlers. This can cause resource usage, such as network traffic, that the user agent SHOULD attribute to the webapp that created the push subscription.

The user agent MAY consider the PushSubscriptionOptions when acquiring permission or determining the permission status.

When a permission is revoked, the user agent MAY fire the pushsubscriptionchange event for subscriptions created with that permission, with the service worker registration associated with the push subscription as registration, a PushSubscription instance representing the push subscription as oldSubscription, and null as newSubscription. The user agent MUST deactivate the affected subscriptions in parallel.

When a service worker registration is unregistered, any associated push subscription MUST be deactivated.

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

The push endpoint of a deactivated push subscription MUST NOT be reused for a new push subscription. This prevents the creation of a persistent identifier that the user cannot remove. This also prevents reuse of the details of one push subscription to send push messages to another push subscription.

User agents MUST implement the Push API to only be available in secure contexts. 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.

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

7. Extensions to the ServiceWorkerRegistration Interface

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

[SecureContext]
partial interface ServiceWorkerRegistration {
    readonly attribute PushManager pushManager;
};

The pushManager attribute exposes a PushManager, which has an associated service worker registration represented by the ServiceWorkerRegistration on which the attribute is exposed.

8. PushManager interface

The PushManager interface defines the operations to access push services.

[Exposed=(Window,Worker),
 SecureContext]
interface PushManager {
    [SameObject]
    static readonly attribute FrozenArray<DOMString> supportedContentEncodings;

    Promise<PushSubscription>    subscribe(optional PushSubscriptionOptionsInit options);
    Promise<PushSubscription?>   getSubscription();
    Promise<PushPermissionState> permissionState(optional PushSubscriptionOptionsInit options);
};

The supportedContentEncodings attribute exposes the sequence of supported content codings that can be used to encrypt the payload of a push message. A content coding is indicated using the Content-Encoding header field when requesting the sending of a push message from the push service.

User agents MUST support the aes128gcm content coding defined in [WEBPUSH-ENCRYPTION], and MAY support content codings defined in previous versions of the draft for compatibility reasons.

The subscribe method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. If the current settings object is not a secure context, reject promise with a DOMException whose name is "SecurityError" and terminate these steps.
4. If the options argument includes a non-null value for the applicationServerKey attribute, run the following substeps:
   1. If the applicationServerKey is provided as a DOMString, set its value to a BufferSource containing the sequence of octets that result from decoding applicationServerKey using the base64url encoding [RFC7515]. If decoding fails, reject promise with a DOMException whose name is "InvalidCharacterError" and terminate these steps.
   2. Ensure that applicationServerKey describes a valid point on the P-256 curve. If the applicationServerKey value is invalid, reject promise with a DOMException whose name is "InvalidAccessError" and terminate these steps.
5. If the options argument does not include a non-null value for the applicationServerKey attribute, and the push service requires one to be given, reject promise with a DOMException whose name is "NotSupportedError" and terminate these steps.
6. Let registration be the PushManager's associated service worker registration.
7. If registration's active worker is null, reject promise with a DOMException whose name is "InvalidStateError" and terminate these steps.
8. Ask the user whether they allow the webapp to receive push messages, unless a prearranged trust relationship applies or the user has already granted or denied permission explicitly for this webapp. Note that a user agent that needs to request permission might be unable to do so if subscribe is invoked from a service worker, in which case permission will be denied automatically.
9. If not granted, reject promise with a DOMException whose name is "NotAllowedError" and terminate these steps.
10. If the Service Worker is already subscribed, run the following substeps:
    1. Retrieve the push subscription associated with the Service Worker.
    2. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
    3. Let subscription be the retrieved subscription.
    4. Compare the options argument with the options attribute of subscription. If any attribute on options contains a different value to that stored for subscription, then reject promise with an InvalidStateError and terminate these steps. The contents of BufferSource values are compared for equality rather than references.
    5. When the request has been completed, resolve promise with subscription.
11. Let subscription be the result of running the create a push subscription steps given options.
12. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
13. Resolve promise with a PushSubscription providing the details of the new subscription.

The getSubscription method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. If the Service Worker is not subscribed, resolve promise with null.
4. Retrieve the push subscription associated with the Service Worker.
5. If there is an error, reject promise with a DOMException whose name is "AbortError" and terminate these steps.
6. When the request has been completed, resolve promise with a PushSubscription providing the details of the retrieved push subscription.

The permissionState method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. Retrieve the push permission status (PushPermissionState) of the requesting webapp.
4. If there is an error, reject promise with no arguments and terminate these steps.
5. When the request has been completed, resolve promise with PushPermissionState providing the push permission status.

Permission to use the push service can be persistent, that is, it does not need to be reconfirmed for subsequent subscriptions if a valid permission exists.

If there is a need to ask for permission, it needs to be done by invoking the subscribe method.

dictionary PushSubscriptionOptionsInit {
    boolean                      userVisibleOnly = false;
    (BufferSource or DOMString)? applicationServerKey = null;
};

[Exposed=(Window,Worker),
 SecureContext]
interface PushSubscriptionOptions {
    readonly attribute boolean      userVisibleOnly;
    [SameObject]
    readonly attribute ArrayBuffer? applicationServerKey;
};

9. PushSubscription interface

A PushSubscription object represents a push subscription.

[Exposed=(Window,Worker),
 SecureContext]
interface PushSubscription {
    readonly attribute USVString               endpoint;
    readonly attribute DOMTimeStamp?           expirationTime;
    [SameObject]
    readonly attribute PushSubscriptionOptions options;
    ArrayBuffer?         getKey(PushEncryptionKeyName name);
    Promise<boolean>     unsubscribe();

    PushSubscriptionJSON toJSON();
};

dictionary PushSubscriptionJSON {
    USVString                    endpoint;
    DOMTimeStamp?                expirationTime;
    record<DOMString, USVString> keys;
};

When getting the endpoint attribute, the user agent MUST return the push endpoint associated with the push subscription. The user agent MUST use a serialization method that does not contain input-dependent branchs (that is, one that is constant time).

When getting the expirationTime attribute, the user agent MUST return the subscription expiration time associated with the push subscription if there is one, or null otherwise.

When getting the options attribute, the user agent MUST return a PushSubscriptionOptions object representing the options associated with the push subscription.

The getKey method retrieves keying material that can be used for encrypting and authenticating messages. When getKey is invoked the following process is followed:

1. Find the internal slot corresponding to the key named by the name argument.
2. If a slot was not found, return null.
3. Initialize a variable key with a newly instantiated ArrayBuffer instance.
4. If the internal slot contains an asymmetric key pair, set the contents of key 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, [WEBPUSH-ENCRYPTION] specifies that the p256dh public key is encoded using the uncompressed format defined in [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 of key to a copy of the value from the internal slot. For example, the auth parameter contains an octet sequence used by the user agent to authenticate messages sent by an application server.
6. Return key.

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

The unsubscribe method when invoked MUST run the following steps:

1. Let promise be a new Promise.
2. Return promise and continue the following steps asynchronously.
3. If the push subscription has already been deactivated, resolve promise with false and terminate these steps.
4. Run the following step in parallel:
   1. Deactivate the push subscription. The user agent MUST NOT deliver any further push messages for the push subscription.

      If the user agent failed to request the push service to deactivate the push subscription, for example because of network failures, it SHOULD retry the request to the push service for a reasonable amount of time.

5. Resolve promise with true.

The toJSON method when invoked MUST run the following steps:

1. Let json be a new PushSubscriptionJSON dictionary.
2. Set json["endpoint"] to the result of getting the underlying value of the endpoint attribute given this PushSubscription object.
3. Set json["expirationTime"] to the result of getting the underlying value of the expirationTime attribute given this PushSubscription object.
4. Let keys be a new empty instance of record<DOMString, USVString> .
5. For each identifier i corresponding to keys in internal slots on the PushSubscription, ordered by the name of the key:
   1. If the internal slot corresponds to an asymmetric key pair, let b be the encoded value of the public key corresponding to the key name i, using the encoding defined for the key name (see getKey).
   2. Otherwise, let b be the value as returned by getKey.
   3. Let s be the URL-safe base64 encoding without padding [RFC4648] of b as a USVString. The user agent MUST use a serialization method that does not branch based on the value of b.
   4. Set keys[i] to s.
6. Set json["keys"] to keys.
7. Return json.

A PushSubscriptionJSON dictionary represents the JSON type of a PushSubscription. In ECMAScript this can be converted into a JSON string through the JSON.stringify function.

The endpoint contains the underlying value of the endpoint attribute.

The expirationTime contains the underlying value of the expirationTime attribute.

The keys record contains an entry for each of the supported PushEncryptionKeyName entries to the URL-safe base64 encoded representation [RFC4648] of its value.

Note that the options to a PushSubscription are not serialized.

enum PushEncryptionKeyName {
    "p256dh",
    "auth"
};

10. PushMessageData interface

[Exposed=ServiceWorker,
 SecureContext]
interface PushMessageData {
    ArrayBuffer arrayBuffer();
    Blob        blob();
    any         json();
    USVString   text();
};

PushMessageData objects have an associated bytes (a byte sequence) set on creation, which is null if there was no data in the push message.

The arrayBuffer method, when invoked, MUST return an ArrayBuffer whose contents are bytes. Exceptions thrown during the creation of the ArrayBuffer object are re-thrown.

The blob method, when invoked, MUST return a Blob whose contents are bytes and type is not provided.

The json method, when invoked, MUST return the result of invoking the initial value of JSON.parse with the result of running utf-8 decode on bytes as argument. Re-throw any exceptions thrown by JSON.parse.

The text method, when invoked, MUST return the result of running utf-8 decode on bytes.

To extract a byte sequence from object, run these steps:

1. Let bytes be an empty byte sequence.
2. Switch on object's type:

   BufferSource

   Set bytes to a copy of object's contents.

   USVString

   Set bytes to the result of running utf-8 encode on object.

3. Return bytes.

11. Events

[Exposed=ServiceWorker,
 SecureContext]
partial interface ServiceWorkerGlobalScope {
    attribute EventHandler onpush;
    attribute EventHandler onpushsubscriptionchange;
};

typedef (BufferSource or USVString) PushMessageDataInit;

dictionary PushEventInit : ExtendableEventInit {
    PushMessageDataInit data;
};

[Constructor(DOMString type, optional PushEventInit eventInitDict),
 Exposed=ServiceWorker,
 SecureContext]
interface PushEvent : ExtendableEvent {
    readonly attribute PushMessageData? data;
};

dictionary PushSubscriptionChangeInit : ExtendableEventInit {
    PushSubscription newSubscription = null;
    PushSubscription oldSubscription = null;
};

[Constructor(DOMString type, optional PushSubscriptionChangeInit eventInitDict),
 Exposed=ServiceWorker,
 SecureContext]
interface PushSubscriptionChangeEvent : ExtendableEvent {
    readonly attribute PushSubscription? newSubscription;
    readonly attribute PushSubscription? oldSubscription;
};

12. PushPermissionState Enumeration

enum PushPermissionState {
    "denied",
    "granted",
    "prompt",
};