add documentation for setVapidDetails method (#787)

* add documentation for setVapidDetails method

document the setVapidDetails method
add warning about Safari and localhost URIs as VAPID subject

* add check for https://localhost to VAPID subject validator

emit sensible warning to user when localhost URI is detected

Author: delfuego

README.md

@@ -193,6 +193,8 @@ that may either be a string URI of the proxy server (eg. http://< hostname >:< p
 or an "options" object with more specific properties.
 - **agent** is the [HTTPS Agent instance](https://nodejs.org/dist/latest/docs/api/https.html#https_class_https_agent) which will be used in the `https.request` method. If the `proxy` options defined, `agent` will be ignored!
 
+> **Note:** As of this writing, if a push notification request contains a VAPID `subject` referencing an `https://localhost` URI (set either using the `options` argument or via the global `setVapidDetails()` method), Safari's push notification endpoint rejects the request with a `BadJwtToken` error.
+
 ### Returns
 
 A promise that resolves if the notification was sent successfully
@@ -250,6 +252,32 @@ None.
 
 <hr />
 
+## setVapidDetails(subject, publicKey, privateKey)
+
+```javascript
+webpush.setVapidDetails(
+  'mailto:[email protected]',
+  process.env.VAPID_PUBLIC_KEY,
+  process.env.VAPID_PRIVATE_KEY
+);
+```
+
+Globally sets the application's VAPID subject, public key, and private key, to be used in subsequent calls to `sendNotification()` and `generateRequestDetails()` that don't specifically override them in their `options` argument.
+
+### Input
+
+The `setVapidDetails` method expects the following input:
+
+- *subject*: the VAPID server contact information, as either an `https:` or `mailto:` URI ([as per the VAPID spec](https://datatracker.ietf.org/doc/html/draft-thomson-webpush-vapid#section-2.1)).
+- *publicKey*: the VAPID public key.
+- *privateKey*: the VAPID private key.
+
+### Returns
+
+None.
+
+<hr />
+
 ## encrypt(userPublicKey, userAuth, payload, contentEncoding)
 
 ```javascript

src/vapid-helper.js

@@ -79,6 +79,8 @@ function validateSubject(subject) {
     const subjectParseResult = url.parse(subject);
     if (!subjectParseResult.hostname) {
       throw new Error('Vapid subject is not a url or mailto url. ' + subject);
+    } else if (subjectParseResult.hostname === 'localhost' && subjectParseResult.protocol === 'https:') {
+      console.warn('VAPID subject points to a localhost web URI, which is unsupported by Apple\'s push notification server and will result in a BadJwtToken error when sending notifications.');
     }
   }
 }