webpush 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b8ab0b45116811a01dc8d7cd726639b4b4f5781
-  data.tar.gz: f684010fd4cd1f75d91affaa73728ba9a45b705e
+  metadata.gz: ef85cc1d7d9a39a57426c5d1d20b89c0c5069407
+  data.tar.gz: 5b964e6fb1bec69c5bb3f331d139ab4b848d063e
 SHA512:
-  metadata.gz: d4c143e92b6b95a6030cca488c2b270cd348a12332b22eaacb987346b9cffc373523b860a434ea9756519df68576a42521ab37663d8084a62ab22c38406f743a
-  data.tar.gz: 48baaa4360ce374f4f2f171bae6235d76e978e1e2db6ca622893058d01e7a7cf4513cf856d19c91dbf8f66638874d3a25ff0a61a435204dac86406f780280471
+  metadata.gz: ca808369991e12634181e0a748ea1c3f8a918ec370f14f7709820a9004305c041dab21b571d610d3db71fdd4ac382f2166641f1375ca345b267db134fbb351be
+  data.tar.gz: 0e95d566e542ce200ee670c12a932d8de8b76f69df13115785fc59d10a8b897df9734b48382656ac97263cbbea23003e92bb4df00fe55e2f214af88964743ae1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Hiroyuki Sakuraba
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -4,7 +4,7 @@
 [![Build Status](https://travis-ci.org/zaru/webpush.svg?branch=master)](https://travis-ci.org/zaru/webpush)
 [![Gem Version](https://badge.fury.io/rb/webpush.svg)](https://badge.fury.io/rb/webpush)
 
-This Gem will send the Web Push API. It supports the encryption necessary to payload.
+This gem makes it possible to send push messages to web browsers from Ruby backends using the [Web Push Protocol](https://tools.ietf.org/html/draft-ietf-webpush-protocol-10). It supports [Message Encryption for Web Push](https://tools.ietf.org/html/draft-ietf-webpush-encryption) to send messages securely from server to user agent.
 
 Payload is supported by Chrome50+, Firefox48+.
 
@@ -26,7 +26,188 @@ Or install it yourself as:
 
 ## Usage
 
-### using the payload
+Sending a web push message to a visitor of your website requires a number of steps:
+
+1. Your server has (optionally) generated (one-time) a set of [Voluntary Application server Identification (VAPID)](https://tools.ietf.org/html/draft-ietf-webpush-vapid-01) keys.
+2. To send messages through Chrome, you have registered your site through the [Google Developer Console](https://console.developers.google.com/) and have obtained a GCM sender id. For using Google's deprecated GCM protocol instead of VAPID, a separate GCM API key from your app settings would also be necessary.
+3. A 'manifest.json' file, linked from your user's page, identifies your app settings, including the GCM sender ID.
+5. Also in the user's web browser, a `serviceWorker` is installed and activated and its `pushManager` property is subscribed to push events with your VAPID public key, with creates a `subscription` JSON object on the client side.
+6. Your server uses the `webpush` gem to send a notification with the `subscription` obtained from the client and an optional payload (the message).
+7. Your service worker is set up to receive `'push'` events. To trigger a desktop notification, the user has accepted the prompt to receive notifications from your site.
+
+### Generating VAPID keys
+
+Use `webpush` to generate a VAPID key that has both a `public_key` and `private_key` attribute to be saved on the server side.
+
+```ruby
+# One-time, on the server
+vapid_key = Webpush.generate_key
+
+# Save these in your application server settings
+vapid_key.public_key
+vapid_key.private_key
+```
+
+### Declaring manifest.json
+
+For Chrome web push, add the GCM sender id to a `manifest.json` file served at the scope of your app (or above), like at the root.
+
+```javascript
+{
+  "name": "My Website",
+  "gcm_sender_id": "1006629465533"
+}
+```
+
+And link to it somewhere in the `<head>` tag:
+
+```html
+<!-- index.html -->
+<link rel="manifest" href="/manifest.json" />
+```
+
+### Installing a service worker
+
+Your application javascript must register a service worker script at an appropriate scope (we're sticking with the root).
+
+```javascript
+// application.js
+// Register the serviceWorker script at /serviceworker.js from your server if supported
+if (navigator.serviceWorker) {
+  navigator.serviceWorker.register('/serviceworker.js')
+    .then(function(reg) {
+       console.log('Service worker change, registered the service worker');
+    });
+}
+// Otherwise, no push notifications :(
+else {
+  console.error('Service worker is not supported in this browser');
+}
+```
+
+### Subscribing to push notifications
+
+The VAPID public key you generated earlier is made available to the client as a `UInt8Array`. To do this, one way would be to expose the urlsafe-decoded bytes from Ruby to JavaScript when rendering the HTML template. (Global variables used here for simplicity).
+
+```javascript
+window.vapidPublicKey = new Uint8Array(<%= Base64.urlsafe_decode64(ENV['VAPID_PUBLIC_KEY']).bytes %>);
+```
+
+Your application javascript would then use the `navigator.serviceWorker.pushManager` to subscribe to push notifications, passing the VAPID public key to the subscription settings.
+
+```javascript
+// application.js
+// When serviceWorker is supported, installed, and activated,
+// subscribe the pushManager property with the vapidPublicKey
+navigator.serviceWorker.ready.then((serviceWorkerRegistration) => {
+  serviceWorkerRegistration.pushManager
+  .subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: window.vapidPublicKey
+  });
+});
+```
+
+Note: If you will not be sending VAPID details, then there is no need generate VAPID
+keys, and the `applicationServerKey` parameter may be omitted from the
+`pushManager.subscribe` call.
+
+### Triggering a web push notification
+
+Hook into an client-side or backend event in your app to deliver a push message. The server must be made aware of the `subscription`. In the example below, we send the JSON generated subscription object to our backend at the "/push" endpoint with a message.
+
+```javascript
+// application.js
+// Send the subscription and message from the client for the backend
+// to set up a push notification
+$(".webpush-button").on("click", (e) => {
+  navigator.serviceWorker.ready
+  .then((serviceWorkerRegistration) => {
+    serviceWorkerRegistration.pushManager.getSubscription()
+    .then((subscription) => {
+      $.post("/push", { subscription: subscription.toJSON(), message: "You clicked a button!" });
+    });
+});
+```
+
+Imagine a Ruby app endpoint that responds to the request by triggering notification through the `webpush` gem.
+
+```ruby
+# app.rb
+# Use the webpush gem API to deliver a push notiifcation merging
+# the message, subscription values, and vapid options
+post "/push" do
+  Webpush.payload_send(
+    message: params[:message]
+    endpoint: params[:subscription][:endpoint],
+    p256dh: params[:subscription][:keys][:p256dh],
+    auth: params[:subscription][:keys][:p256dh],
+    vapid: {
+      subject: "mailto:sender@example.com",
+      public_key: ENV['VAPID_PUBLIC_KEY'],
+      private_key: ENV['VAPID_PRIVATE_KEY']
+    }
+  )
+end
+```
+
+Note: the VAPID options should be omitted if the client-side subscription was
+generated without the `applicationServerKey` parameter described earlier.
+
+### Receiving the push event
+
+Your `/serviceworker.js` script can respond to `'push'` events. One action it can take is to trigger  desktop notifications by calling `showNotification` on the `registration` property.
+
+```javascript
+// serviceworker.js
+// The serviceworker context can respond to 'push' events and trigger
+// notifications on the registration property
+self.addEventListener("push", (event) => {
+  let title = (event.data && event.data.text()) || "Yay a message";
+  let body = "We have received a push message";
+  let tag = "push-simple-demo-notification-tag";
+  let icon = '/assets/my-logo-120x120.png';
+
+  event.waitUntil(
+    self.registration.showNotification(title, { body, icon, tag })
+  )
+});
+```
+
+Before the notifications can be displayed, the user must grant permission for [notifications](https://developer.mozilla.org/en-US/docs/Web/API/notification) in a browser prompt, using something like the example below.
+
+```javascript
+// application.js
+
+// Let's check if the browser supports notifications
+if (!("Notification" in window)) {
+  console.error("This browser does not support desktop notification");
+}
+
+// Let's check whether notification permissions have already been granted
+else if (Notification.permission === "granted") {
+  console.log("Permission to receive notifications has been granted");
+}
+
+// Otherwise, we need to ask the user for permission
+else if (Notification.permission !== 'denied') {
+  Notification.requestPermission(function (permission) {
+    // If the user accepts, let's create a notification
+    if (permission === "granted") {
+      console.log("Permission to receive notifications has been granted");
+    }
+  });
+}
+```
+
+If everything worked, you should see a desktop notification triggered via web
+push. Yay!
+
+Note: if you're using Rails, check out [serviceworker-rails](https://github.com/rossta/serviceworker-rails), a gem that makes it easier to host serviceworker scripts and manifest.json files at canonical endpoints (i.e., non-digested URLs) while taking advantage of the asset pipeline.
+
+## API
+
+### With a payload
 
 ```ruby
 message = {
@@ -36,22 +217,25 @@ message = {
 }
 
 Webpush.payload_send(
-  endpoint: "https://android.googleapis.com/gcm/send/eah7hak....",
+  endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
   message: JSON.generate(message),
   p256dh: "BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...",
   auth: "aW1hcmthcmFpa3V6ZQ==",
-  ttl: 600, #optional, ttl in seconds, defaults to 2419200 (4 weeks)
-  api_key: "[GoogleDeveloper APIKEY]" # optional, not used in Firefox.
+  ttl: 600 #optional, ttl in seconds, defaults to 2419200 (4 weeks),
+  vapid: {
+    subject: "mailto:sender@example.com",
+    public_key: ENV['VAPID_PUBLIC_KEY'],
+    private_key: ENV['VAPID_PRIVATE_KEY']
+  }
 )
 ```
 
-### not use the payload
+### Without a payload
 
 ```ruby
 Webpush.payload_send(
-  endpoint: "https://android.googleapis.com/gcm/send/eah7hak....",
-  ttl: 600, #optional, ttl in seconds, defaults to 2419200 (4 weeks)
-  api_key: "[GoogleDeveloper APIKEY]" # optional, not used in Firefox.
+  endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
+  ttl: 600 #optional, ttl in seconds, defaults to 2419200 (4 weeks)
 )
 ```
 

data/lib/webpush.rb

@@ -5,15 +5,12 @@ require 'net/http'
 require 'json'
 
 require 'webpush/version'
+require 'webpush/errors'
+require 'webpush/vapid_key'
 require 'webpush/encryption'
 require 'webpush/request'
 
 module Webpush
-
-  # It is temporary URL until supported by the GCM server.
-  GCM_URL = 'https://android.googleapis.com/gcm/send'
-  TEMP_GCM_URL = 'https://gcm-http.googleapis.com/gcm'
-
   class << self
     # Deliver the payload to the required endpoint given by the JavaScript
     # PushSubscription. Including an optional message requires p256dh and
@@ -23,23 +20,32 @@ module Webpush
     # @param message [String] the optional payload
     # @param p256dh [String] the user's public ECDH key given by the PushSubscription
     # @param auth [String] the user's private ECDH key given by the PushSubscription
+    # @param vapid [Hash<Symbol,String>] options for VAPID
+    # @option vapid [String] :subject contact URI for the app server as a "mailto:" or an "https:"
+    # @option vapid [String] :public_key the VAPID public key
+    # @option vapid [String] :private_key the VAPID private key
     # @param options [Hash<Symbol,String>] additional options for the notification
-    # @option options [String] :api_key required for Google, omit for Firefox
     # @option options [#to_s] :ttl Time-to-live in seconds
-    def payload_send(endpoint:, message: "", p256dh: "", auth: "", **options)
-      endpoint = endpoint.gsub(GCM_URL, TEMP_GCM_URL)
-
-      payload = build_payload(message, p256dh, auth)
-
-      Webpush::Request.new(endpoint, options.merge(payload: payload)).perform
+    def payload_send(message: "", endpoint:, p256dh: "", auth: "", vapid: {}, **options)
+      subscription = {
+        endpoint: endpoint,
+        keys: {
+          p256dh: p256dh,
+          auth: auth
+        }
+      }
+      Webpush::Request.new(
+        message: message,
+        subscription: subscription,
+        vapid: vapid,
+        **options
+      ).perform
     end
 
-    private
-
-    def build_payload(message, p256dh, auth)
-      return {} if message.nil? || message.empty?
-
-      Webpush::Encryption.encrypt(message, p256dh, auth)
+    # public_key: vapid_key.public_key.to_bn.to_s(2)
+    # private_key: vapid_key.private_key.to_s(2)
+    def generate_key
+      VapidKey.new
     end
   end
 end

data/lib/webpush/encryption.rb

@@ -36,6 +36,7 @@ module Webpush
         ciphertext: ciphertext,
         salt: salt,
         server_public_key_bn: convert16bit(server_public_key_bn),
+        server_public_key: server_public_key_bn.to_s(2),
         shared_secret: shared_secret
       }
     end

data/lib/webpush/errors.rb

@@ -0,0 +1,9 @@
+module Webpush
+  class Error < RuntimeError; end
+
+  class ConfigurationError < Error; end
+
+  class ResponseError < Error; end
+
+  class InvalidSubscription < ResponseError; end
+end

data/lib/webpush/request.rb

@@ -1,20 +1,21 @@
-module Webpush
-
-  class ResponseError < RuntimeError
-  end
+require 'jwt'
+require 'base64'
 
-  class InvalidSubscription < ResponseError
-  end
+module Webpush
+  # It is temporary URL until supported by the GCM server.
+  GCM_URL = 'https://android.googleapis.com/gcm/send'
+  TEMP_GCM_URL = 'https://gcm-http.googleapis.com/gcm'
 
   class Request
-    def initialize(endpoint, options = {})
-      @endpoint = endpoint
+    def initialize(message: "", subscription:, vapid:, **options)
+      endpoint = subscription.fetch(:endpoint)
+      @endpoint = endpoint.gsub(GCM_URL, TEMP_GCM_URL)
+      @payload = build_payload(message, subscription)
+      @vapid_options = vapid
       @options = default_options.merge(options)
-      @payload = @options.delete(:payload) || {}
     end
 
     def perform
-      uri = URI.parse(@endpoint)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
       req = Net::HTTP::Post.new(uri.request_uri, headers)
@@ -36,52 +37,114 @@ module Webpush
       headers["Content-Type"] = "application/octet-stream"
       headers["Ttl"]          = ttl
 
-      if encrypted_payload?
+      if @payload.has_key?(:server_public_key)
         headers["Content-Encoding"] = "aesgcm"
         headers["Encryption"] = "salt=#{salt_param}"
         headers["Crypto-Key"] = "dh=#{dh_param}"
       end
 
-      headers["Authorization"] = "key=#{api_key}" if api_key?
+      if api_key?
+        headers["Authorization"] = api_key
+      elsif vapid?
+        vapid_headers = build_vapid_headers
+        headers["Authorization"] = vapid_headers["Authorization"]
+        headers["Crypto-Key"] = [ headers["Crypto-Key"], vapid_headers["Crypto-Key"] ].compact.join(";")
+      end
 
       headers
     end
 
+    def build_vapid_headers
+      vapid_key = VapidKey.from_keys(vapid_public_key, vapid_private_key)
+      jwt = JWT.encode(jwt_payload, vapid_key.curve, 'ES256')
+      p256ecdsa = vapid_key.public_key_for_push_header
+
+      {
+        'Authorization' => 'WebPush ' + jwt,
+        'Crypto-Key' => 'p256ecdsa=' + p256ecdsa,
+      }
+    end
+
     def body
       @payload.fetch(:ciphertext, "")
     end
 
     private
 
+    def uri
+      @uri ||= URI.parse(@endpoint)
+    end
+
     def ttl
       @options.fetch(:ttl).to_s
     end
 
-    def api_key
-      @options.fetch(:api_key, nil)
+    def dh_param
+      trim_encode64(@payload.fetch(:server_public_key))
     end
 
-    def api_key?
-      !(api_key.nil? || api_key.empty?) && @endpoint =~ /\Ahttps:\/\/(android|gcm-http)\.googleapis\.com/
+    def salt_param
+      trim_encode64(@payload.fetch(:salt))
     end
 
-    def encrypted_payload?
-      [:ciphertext, :server_public_key_bn, :salt].all? { |key| @payload.has_key?(key) }
+    def jwt_payload
+      {
+        aud: audience,
+        exp: Time.now.to_i + expiration,
+        sub: subject,
+      }
     end
 
-    def dh_param
-      Base64.urlsafe_encode64(@payload.fetch(:server_public_key_bn)).delete('=')
+    def audience
+      uri.scheme + "://" + uri.host
     end
 
-    def salt_param
-      Base64.urlsafe_encode64(@payload.fetch(:salt)).delete('=')
+    def expiration
+      @vapid_options.fetch(:expiration, 24*60*60)
+    end
+
+    def subject
+      @vapid_options.fetch(:subject, 'sender@example.com')
+    end
+
+    def vapid_public_key
+      @vapid_options.fetch(:public_key, nil)
+    end
+
+    def vapid_private_key
+      @vapid_options.fetch(:private_key, nil)
     end
 
     def default_options
       {
-        api_key: nil,
         ttl: 60*60*24*7*4 # 4 weeks
       }
     end
+
+    def build_payload(message, subscription)
+      return {} if message.nil? || message.empty?
+
+      encrypt_payload(message, subscription.fetch(:keys))
+    end
+
+    def encrypt_payload(message, p256dh:, auth:)
+      Encryption.encrypt(message, p256dh, auth)
+    end
+
+    def api_key
+      @options.fetch(:api_key, nil)
+    end
+
+    def api_key?
+      !(api_key.nil? || api_key.empty?) && @endpoint =~ /\Ahttps:\/\/(android|gcm-http)\.googleapis\.com/
+    end
+
+    def vapid?
+      @vapid_options.any?
+    end
+
+    def trim_encode64(bin)
+      Base64.urlsafe_encode64(bin).delete('=')
+    end
   end
 end

data/lib/webpush/vapid_key.rb

@@ -0,0 +1,75 @@
+module Webpush
+  class VapidKey
+    def self.from_keys(public_key, private_key)
+      key = new
+      key.public_key = public_key
+      key.private_key = private_key
+
+      key
+    end
+
+    attr_reader :curve
+
+    def initialize
+      @curve = OpenSSL::PKey::EC.new('prime256v1')
+      @curve.generate_key
+    end
+
+    # Retrieve the encoded EC public key for server-side storage
+    # @return encoded binary representaion of 65-byte VAPID public key
+    def public_key
+      encode64(curve.public_key.to_bn.to_s(2))
+    end
+
+    # Retrieve EC public key for Web Push
+    # @return the encoded VAPID public key suitable for Web Push transport
+    def public_key_for_push_header
+      trim_encode64(curve.public_key.to_bn.to_s(2))
+    end
+
+    # Convenience
+    # @return base64 urlsafe-encoded binary representaion of 32-byte VAPID private key
+    def private_key
+      Base64.urlsafe_encode64(curve.private_key.to_s(2))
+    end
+
+    def public_key=(key)
+      @curve.public_key = OpenSSL::PKey::EC::Point.new(group, to_big_num(key))
+    end
+
+    def private_key=(key)
+      @curve.private_key = to_big_num(key)
+    end
+
+    def curve_name
+      group.curve_name
+    end
+
+    def group
+      curve.group
+    end
+
+    def to_h
+      { public_key: public_key, private_key: private_key }
+    end
+    alias to_hash to_h
+
+    def inspect
+      "#<#{self.class}:#{object_id.to_s(16)} #{to_h.map { |k, v| ":#{k}=#{v}" }.join(" ")}>"
+    end
+
+    private
+
+    def to_big_num(key)
+      OpenSSL::BN.new(Base64.urlsafe_decode64(key), 2)
+    end
+
+    def encode64(bin)
+      Base64.urlsafe_encode64(bin)
+    end
+
+    def trim_encode64(bin)
+      encode64(bin).delete('=')
+    end
+  end
+end

data/lib/webpush/version.rb

@@ -1,3 +1,3 @@
 module Webpush
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

data/webpush.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "hkdf", "~> 0.2"
+  spec.add_dependency "jwt"
 
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency 'pry'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: webpush
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - zaru@sakuraba
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-14 00:00:00.000000000 Z
+date: 2016-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hkdf
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -119,6 +133,7 @@ files:
 - ".rspec"
 - ".travis.yml"
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
@@ -127,7 +142,9 @@ files:
 - bin/setup
 - lib/webpush.rb
 - lib/webpush/encryption.rb
+- lib/webpush/errors.rb
 - lib/webpush/request.rb
+- lib/webpush/vapid_key.rb
 - lib/webpush/version.rb
 - webpush.gemspec
 homepage: https://github.com/zaru/webpush
@@ -149,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Encryption Utilities for Web Push payload.