update readme, rename/update vapid task, add ex_doc

Author: kenichi

README.md

@@ -18,67 +18,44 @@ def deps do
 end
 ```
 
-## Usage
+## Configuration
 
-`serviceWorker.js` example (abridged):
+`WebPush` needs VAPID keys to work. Run `mix web_push.vapid` and adapt the
+generated config to your needs:
 
-```javascript
-self.addEventListener('push', function(event) {
-  event.waitUntil(
-    self.clients.matchAll().then(function(_clientList) {
-      const payload = event.data.json();
-      return self.registration.showNotification(payload.title, { body: payload.body, });
-    })
-  );
-});
 ```
+$ mix web_push.vapid
+# in config/config.exs:
+
+    config :web_push, :vapid,
+      public_key: "<base64 encoded public key>"
+      subject: "[email protected]"
+
+# in config/runtime.exs:
 
-`notify.js` example:
+    config :web_push, :vapid,
+      private_key: System.fetch_env!("WEB_PUSH_VAPID_PRIVATE_KEY")
+
+# in your environment:
+
+    export WEB_PUSH_VAPID_PRIVATE_KEY=<base64 encoded private key>
+```
+
+## Usage
+
+Your application should handle getting and persisting subscription data from
+browsers. The implementation is up to you but the VAPID public key is required
+to be presented when calling `pushManager.subscribe()`:
 
 ```javascript
-function postSubscription(subscription) {
-  fetch("https://app.example.com/subscriptions", {
-    body: JSON.stringify({ subscription }),
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-    },
-  });
-}
-
-document.getElementById("#request-permission").addEventListener("click", (_event) => {
-  Notification.requestPermission()
-    .then((permission) => {
-      if (permission === "granted") {
-        navigator.serviceWorker
-          .register("https://app.example.com/serviceWorker.js", {scope: "https://app.example.com"})
-          .then((registration) => {
-            registration.pushManager.getSubscription()
-              .then((subscription) => {
-                if (subscription) {
-                  postSubscription(subscription);
-                } else {
-                  document.getElementById("#subscribe").addEventListener("click", (_event) => {
-                    const subscribeOpts = {
-                      userVisibleOnly: true,
-                      applicationServerKey: "VAPID public key",
-                    };
-
-                    registration.pushManager.subscribe(subscribeOpts)
-                      .then(postSubscription);
-                  });
-                }
-              });
-              .catch(console.error);
-
-          })
-          .catch(console.error);
-      }
-    })
-    .catch(console.error);
-});
+pushManager.subscribe({
+  userVisibleOnly: true,
+  applicationServerKey: vapidPublicKey,
+}).then(...);
 ```
 
+Once you have your subscription data, you may construct a `WebPush.Request` and
+use it to make the push notification via the HTTP client of your choice.
 
 ```elixir
 # create the struct from the subscription JSON data
@@ -87,7 +64,7 @@ subscription =
   {"endpoint":"https://push.example.com/123","keys":{"p256dh":"user_agent_public_key","auth":"auth_secret"}}
   """)
 
-# structured message, see example serviceWorker.js above
+# structured message, see example serviceWorker.js linked below
 message = %{title: "Notification Title", body: "lorem ipsum etc"}
 
 # generate request details
@@ -113,7 +90,26 @@ request.headers
 Tesla.post(request.endpoint, request.body, headers: Map.to_list(request.headers))
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/web_push>.
+## tl()
+
+#### Motivation && Inspiration
+
+* [web-push-elixir](https://github.com/midarrlabs/web-push-elixir)
+* [web-push-encryption](https://github.com/tuvistavie/elixir-web-push-encryption)
+* [web-push](https://github.com/web-push-libs/web-push)
+* [erl_web_push](https://github.com/truqu/erl_web_push)
+
+#### Useful Links
+
+* https://datatracker.ietf.org/doc/html/rfc8291/
+* https://datatracker.ietf.org/doc/html/rfc8188/
+* https://datatracker.ietf.org/doc/html/rfc3279/
+
+* https://mozilla-services.github.io/WebPushDataTestPage/
+* https://developer.mozilla.org/en-US/docs/Web/API/Push_API
+* https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers
+* https://github.com/mdn/serviceworker-cookbook/tree/master/push-payload
+* https://blog.mozilla.org/services/2016/08/23/sending-vapid-identified-webpush-notifications-via-mozillas-push-service/
+* https://hacks.mozilla.org/2017/05/debugging-web-push-in-mozilla-firefox/
 
+* https://developer.apple.com/documentation/usernotifications/sending-web-push-notifications-in-web-apps-and-browsers

lib/mix/tasks/web_push/vapid.ex

@@ -0,0 +1,46 @@
+defmodule Mix.Tasks.WebPush.Vapid do
+  @moduledoc """
+  Generate VAPID keys for config.
+
+  Example:
+
+      $ mix web_push.vapid
+
+  """
+
+  @shortdoc "Generate VAPID keys for config"
+
+  use Mix.Task
+
+  @impl true
+  def run(_args) do
+    :ecdh
+    |> :crypto.generate_key(:prime256v1)
+    |> encode()
+    |> build_config_message()
+    |> IO.puts()
+  end
+
+  defp encode({public_key, private_key}), do: {encode(public_key), encode(private_key)}
+
+  defp encode(key), do: Base.url_encode64(key, padding: false)
+
+  defp build_config_message({public_key, private_key}) do
+    """
+    # in config/config.exs:
+
+        config :web_push, :vapid,
+          public_key: "#{public_key}",
+          subject: "[email protected]"
+
+    # in config/runtime.exs:
+
+        config :web_push, :vapid,
+          private_key: System.fetch_env!("WEB_PUSH_VAPID_PRIVATE_KEY")
+
+    # in your environment:
+
+        export WEB_PUSH_VAPID_PRIVATE_KEY=#{private_key}
+    """
+  end
+end

lib/web_push.ex

@@ -1,6 +1,6 @@
 defmodule WebPush do
   @moduledoc """
-  Web Push notifications.
+  Web Push notifications via `aes128gcm`.
 
   Implementation of RFC 8291, 8188, & 5689.
   """
@@ -142,7 +142,7 @@ defmodule WebPush do
         # number of zero octets.  The last record uses a padding delimiter
         # octet set to the value 2, all other records have a padding delimiter
         # octet value of 1.
-        payload <> <<2>>,
+        <<payload::binary, 2>>,
         # The additional data passed to each invocation of AEAD_AES_128_GCM is
         # a zero-length octet sequence.
         <<>>,
@@ -166,18 +166,12 @@ defmodule WebPush do
 
   @spec hkdf_extract(salt(), input_keying_material()) :: psuedo_random_key()
   defp hkdf_extract(salt, input_keying_material) do
-    :crypto.mac_init(:hmac, :sha256, salt)
-    |> :crypto.mac_update(input_keying_material)
-    |> :crypto.mac_final()
+    :crypto.mac(:hmac, :sha256, salt, input_keying_material)
   end
 
   @spec hkdf_expand(psuedo_random_key(), info(), length()) :: key()
-  defp hkdf_expand(prk, info, length) do
-    :crypto.mac_init(:hmac, :sha256, prk)
-    |> :crypto.mac_update(info)
-    |> :crypto.mac_update(<<1>>)
-    |> :crypto.mac_final()
-    |> :binary.part(0, length)
+  defp hkdf_expand(psuedo_random_key, info, length) do
+    :crypto.macN(:hmac, :sha256, psuedo_random_key, <<info::binary, 1>>, length)
   end
 
   @spec fetch_vapid!(vapid_key(), boolean()) :: String.t()

mix.exs

@@ -41,6 +41,7 @@ defmodule WebPush.MixProject do
     [
       {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
       {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false},
+      {:ex_doc, "~> 0.34", only: :dev, runtime: false},
       {:jose, "~> 1.11"}
     ]
   end

mix.lock

@@ -2,8 +2,14 @@
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
   "credo": {:hex, :credo, "1.7.7", "771445037228f763f9b2afd612b6aa2fd8e28432a95dbbc60d8e03ce71ba4446", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "8bc87496c9aaacdc3f90f01b7b0582467b69b4bd2441fe8aae3109d843cc2f2e"},
   "dialyxir": {:hex, :dialyxir, "1.4.3", "edd0124f358f0b9e95bfe53a9fcf806d615d8f838e2202a9f430d59566b6b53b", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "bf2cfb75cd5c5006bec30141b131663299c661a864ec7fbbc72dfa557487a986"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"},
   "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"},
+  "ex_doc": {:hex, :ex_doc, "0.34.2", "13eedf3844ccdce25cfd837b99bea9ad92c4e511233199440488d217c92571e8", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "5ce5f16b41208a50106afed3de6a2ed34f4acfd65715b82a0b84b49d995f95c1"},
   "file_system": {:hex, :file_system, "1.0.1", "79e8ceaddb0416f8b8cd02a0127bdbababe7bf4a23d2a395b983c1f8b3f73edd", [:mix], [], "hexpm", "4414d1f38863ddf9120720cd976fce5bdde8e91d8283353f0e31850fa89feb9e"},
   "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},
   "jose": {:hex, :jose, "1.11.10", "a903f5227417bd2a08c8a00a0cbcc458118be84480955e8d251297a425723f83", [:mix, :rebar3], [], "hexpm", "0d6cd36ff8ba174db29148fc112b5842186b68a90ce9fc2b3ec3afe76593e614"},
+  "makeup": {:hex, :makeup, "1.1.2", "9ba8837913bdf757787e71c1581c21f9d2455f4dd04cfca785c70bbfff1a76a3", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cce1566b81fbcbd21eca8ffe808f33b221f9eee2cbc7a1706fc3da9ff18e6cac"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
 }