doc: Update docs to indicate that sub is required. (#758)

We require the `sub` so that we can contact folk that are possibly doing
questionable things. While we don't validate the contact URI, if we see
a problem and we can't contact folk, it probably means we're just going
to block them.

Closes #SYNC-3678

autoendpoint/src/headers/vapid.rs

@@ -11,6 +11,14 @@ use autopush_common::util::{sec_since_epoch, ONE_DAY_IN_SECONDS};
 
 pub const ALLOWED_SCHEMES: [&str; 3] = ["bearer", "webpush", "vapid"];
 
+/*
+The Assertion block for the VAPID header.
+
+Please note: We require the `sub` claim in addition to the `exp` and `aud`.
+See [HTTP Endpoints for Notficiations::Lexicon::{vapid_key}](https://mozilla-services.github.io/autopush-rs/http.html#lexicon-1)
+for details.
+
+ */
 #[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
 pub struct VapidClaims {
     pub exp: u64,

docs/src/http.md

@@ -253,10 +253,18 @@ An example of the Authorization header would be:
 _The [VAPID Key](https://datatracker.ietf.org/doc/html/rfc8292#section-3.2) provided by the subscribing third party_
 
 The VAPID key is optional and provides a way for an application server to voluntarily identify itself.
-When the VAPID key is provided, autopush will return an endpoint that can only be used by the application server that provided the key.
-**The VAPID key is formatted as a URL-safe Base64 encoded string with no padding.**
 
+_*Please Note*_: While the VAPID key is optional, if it is included, the VAPID asserion block _must_ contain a `sub` field containing the publishing contact information as a vaild URI designator. (e.g. `mailto:[email protected]` or `https://example.org/contact`). As an example, a minimal VAPID assertion block would contain:
+
+```json
+{"aud": "https://updates.push.services.mozilla.com", "exp": 1725468595, "sub": "mailto:[email protected]"}
+```
+
+Where `exp` and `sub` reflect the expiration time and publishing contact information. The contact information is used in case of an issue with use of the Push service and is never used for marketing purposes.
+
+When the VAPID key is provided, autopush will return an endpoint that can only be used by the application server that provided the key.
 
+**The VAPID key is formatted as a URL-safe Base64 encoded string with no padding.**
 
 ## Calls