passkit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14879f088666efc426ff4d2861589f526991129dd83f91a70d7bf8867f64071c
-  data.tar.gz: d52fca69a103bb5fd958502449e61ad194ba41928b8d1337c7f715cd799add79
+  metadata.gz: abe44c75069e0fc397f9a1f7155dd811a0341de723223ca3fdfbe7543b9a8a6c
+  data.tar.gz: c8a36754d91a1dd241064cdf0e5b3d3defbf5df54d13c3135bf56b5dc8564b19
 SHA512:
-  metadata.gz: 37a9f00cc34e6f272ebb811a199fb9457eb750297b616bfd487cb091b48dad0fae0d5782674c50a70033eadd803767bdccc11b53f6e6b4149b5ecbf5c619bf54
-  data.tar.gz: ac193511be72f80a214a3e4bf4dd149430fc2682b4381368e6352e19635010298c623fe1b6c51b9b6f1323a062f023f1c2c45e53123a4fc801e2dfe9785be80d
+  metadata.gz: 1137d58cf9f2b560a0363ab2c14868eca913960bd1eea70e3737dcdc5cff3411de06a72988ffce0cb910d14ab30de68502da3542bbe48d4f17e262b1c3c48f8e
+  data.tar.gz: 4d6e5d66d65705b8b01c84820559b4244be5ad1f9ea71ec58b9c86fd133933bea766783c192250571cc80ad28c4b90c0e57e22affc8bbdfeff8c9ded6cbc3827

data/README.md

@@ -1,6 +1,27 @@
-# Passkit
+# <img src="./docs/wallet.png" alt="Goboony" height="50"/> Passkit
+
+Your out-of-the-box solution to start serving Wallet Passes in your Ruby On Rails application.
+
+Do you have a QRCode or a Barcode anywhere in your app that you want to distribute as Wallet Pass, compatible for iOS and Android? Look no further!
+
+This gem provides everything that is necessary, and gives you all the steps to follow for what we cannot provide.
+
+We provide:
+
+* A (not yet) fancy dashboard to manage your passes, registered devices and logs
+* All API endpoints to serve your passes: create, register, update, unregister, etc...
+* All ActiveRecord models necessary
+* A BasePass model that you can extend to create your own passes
+* Some helpers to generate the necessary URLs, so that you can include them in the emails
+* Examples for everything
+
+We don't provide yet (WIP):
+
+* Full tests coverage. We are working on it!
+* A fancy dashboard. Pull requests are welcome!
+* Push notifications. Pull requests are welcome!
+* Google Wallet passes. We use https://walletpasses.io/ on Android to read .pkpass format.
 
-Generate Wallet Passes for iOS.
 
 ## Installation
 
@@ -18,9 +39,100 @@ Or install it yourself as:
 
     $ gem install passkit
 
+Run the initializer:
+
+    $ rails g passkit:install
+
+that will generate the migrations and the initializer file.
+
+Mount the engine in your routes.rb:
+
+```ruby
+mount Passkit::Engine => '/passkit', as: 'passkit'
+```
+
+and run `rails db:migrate`.
+
 ## Usage
 
-TODO: Write usage instructions here
+If you followed the installation steps, you already saw that Passkit provides 
+you the tables and ActiveRecord models, and also an engine the necessary APIs already implemented.
+
+Now is your turn. Before proceeding, you need to set these ENV variables:
+* `PASSKIT_WEB_SERVICE_HOST`
+* `PASSKIT_CERTIFICATE_KEY`
+* `PASSKIT_PRIVATE_P12_CERTIFICATE`
+* `PASSKIT_APPLE_INTERMEDIATE_CERTIFICATE`
+* `PASSKIT_APPLE_TEAM_IDENTIFIER`
+* `PASSKIT_PASS_TYPE_IDENTIFIER`
+
+We have a [specific guide on how to get all these](docs/passkit_environment_variables.md), please follow it.
+You cannot do any of the following steps without these variables set, and we cannot do the work for you there.
+
+### Check what is available
+
+If you followed the installation steps and you have the ENV variables set, we can start looking at what is provided for you.
+
+Head to `http://localhost:3000/passkit/previews` and you will see a first ExampleStoreCard available for download.
+You can click on the button and you will obtain a `.pkpass` file that you can simply open or install on your phone.
+
+If you use mailer previews, you can create the following file in `spec/mailers/previews/passkit/example_mailer_preview.rb`:
+
+```ruby
+module Passkit
+  class ExampleMailerPreview < ActionMailer::Preview
+    def example_email
+      Passkit::ExampleMailer.example_email
+    end
+  end
+end
+```
+
+and head to `http://localhost:3000/rails/mailers/` to see an example of email with links to download the Wallet Pass.
+
+Please check the source code of the [ExampleStoreCard](lib/passkit/example_store_card.rb) and [ExampleMailer](app/mailers/passkit/example_mailer.rb) to see how to create and distribute your own Wallet Passes.
+Looking at the examples, is the easiest way to get started.
+
+### Create your own Wallet Pass
+
+You can create your own Wallet Passes by creating a new class that inherits from `Passkit::BasePass` and defining the methods that you want to override.
+You can define colors, fields and texts. You can also define the logo and the background image.
+
+You can place the images in a 'private/passkit/<your_downcased_passname>' folder.
+There is a [dummy app in the gem](test/dummy) that you can use to check how to create your own Wallet Passes.
+
+### Serve your Wallet Pass
+
+Use the [Passkit::UrlGenerator](lib/passkit/url_generator.rb) to generate the URL to serve your Wallet Pass. You can initialize it with:
+
+```ruby
+Passkit::UrlGenerator.new(pass_class: Passkit::MyPass, generator: User.find(1))
+```
+
+and then use `.android` or `.ios` to get the URL to serve the Wallet Pass.
+Again, check the example mailer included in the gem to see how to use it.
+
+## Debug issues 
+
+* On Mac, open the `Console.app` to view the errors.
+* Check the logs on http://localhost:3000/passkit/logs
+* In case of error "The passTypeIdentifier or teamIdentifier provided may not match your certificate, 
+or the certificate trust chain could not be verified." the certificate (p12) might be expired.
+
+
+* Setup ngrok and start it
+* Configure your `HOST: 'https://xxx.ngrok.io'` on `config/application.yml` (make sure is https!)
+* Set `config.hosts = nil` in `config/environments/development.rb`
+* Head to the `/rails/mailers/` and preview an email containing a pass
+* Download the pkpass and open it
+
+
+ Here are the rough steps to generate a new one:
+* Access https://developer.apple.com/account/resources/identifiers/passTypeId/edit/F578W7LDT9/pass.ch.renuo.loyalty.
+* Click "Create Certificate".
+* Follow the guide to generate a new Certificate Signing Request and use operations@renuo.ch as email address and Renuo AG as organization name.
+* Convert the certificate to p12 using Keychain Access and re-use the same password.
+* Re-upload the new certificate to the servers.
 
 ## Development
 
@@ -30,7 +142,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/passkit. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/passkit/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/coorasse/passkit. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/coorasse/passkit/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -38,4 +150,8 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Passkit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/passkit/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Passkit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/coorasse/passkit/blob/master/CODE_OF_CONDUCT.md).
+
+## Credits
+
+<a href="https://www.flaticon.com/free-icons/credit-card" title="credit card icons">Credit card icons created by Iconfromus - Flaticon</a>

data/app/controllers/passkit/api/v1/logs_controller.rb

@@ -0,0 +1,14 @@
+module Passkit
+  module Api
+    module V1
+      class LogsController < ActionController::API
+        def create
+          params[:logs].each do |message|
+            Log.create!(content: message)
+          end
+          render json: {}, status: :ok
+        end
+      end
+    end
+  end
+end

data/app/controllers/passkit/api/v1/passes_controller.rb

@@ -0,0 +1,55 @@
+module Passkit
+  module Api
+    module V1
+      class PassesController < ActionController::API
+        before_action :decrypt_payload, only: :create
+
+        def create
+          send_file(fetch_pass(@payload))
+        end
+
+        # @return If request is authorized, returns HTTP status 200 with a payload of the pass data.
+        # @return If the request is not authorized, returns HTTP status 401.
+        # @return Otherwise, returns the appropriate standard HTTP status.
+        def show
+          authentication_token = request.headers["Authorization"]&.split(" ") & [1]
+          unless authentication_token.present?
+            render json: {}, status: :unauthorized
+            return
+          end
+
+          pass = Pass.find_by(serial_number: params[:serial_number], authentication_token: authentication_token)
+          unless pass
+            render json: {}, status: :unauthorized
+            return
+          end
+
+          pass_output_path = Passkit::Generator.new(pass).generate_and_sign
+
+          response.headers["last-modified"] = pass.generator.updated_at.strftime("%Y-%m-%d %H:%M:%S")
+          if request.headers["If-Modified-Since"].nil? ||
+              (pass.generator.updated_at.to_i > Time.zone.parse(request.headers["If-Modified-Since"]).to_i)
+            send_file(pass_output_path)
+          else
+            head :not_modified
+          end
+        end
+
+        private
+
+        def decrypt_payload
+          @payload = Passkit::UrlEncrypt.decrypt(params[:payload])
+          if DateTime.parse(@payload[:valid_until]).past?
+            head :not_found
+          end
+        end
+
+        def fetch_pass(payload)
+          generator_class = payload[:generator_class].constantize
+          generator = generator_class.find(payload[:generator_id])
+          Passkit::Factory.create_pass(generator, payload[:pass_class])
+        end
+      end
+    end
+  end
+end

data/app/controllers/passkit/api/v1/registrations_controller.rb

@@ -0,0 +1,115 @@
+module Passkit
+  module Api
+    module V1
+      # TODO: check with authentication_token
+      # This Class Implements the Apple PassKit API
+      # @see Apple: https://developer.apple.com/library/archive/documentation/PassKit/Reference/PassKit_WebService/WebService.html
+      # @see Android: https://walletpasses.io/developer/
+      class RegistrationsController < ActionController::API
+        before_action :load_pass, only: %i[create destroy]
+        before_action :load_device, only: %i[show]
+
+        # @return If the serial number is already registered for this device, returns HTTP status 200.
+        # @return If registration succeeds, returns HTTP status 201.
+        # @return If the request is not authorized, returns HTTP status 401.
+        # @return Otherwise, returns the appropriate standard HTTP status.
+        def create
+          if @pass.devices.find_by(identifier: params[:device_id])
+            render json: {}, status: :ok
+            return
+          end
+
+          register_device
+          render json: {}, status: :created
+        end
+
+        # @return If there are matching passes, returns HTTP status 200
+        #         with a JSON dictionary with the following keys and values:
+        #         lastUpdated (string): The current modification tag.
+        #         serialNumbers (array of strings): The serial numbers of the matching passes.
+        # @return If there are no matching passes, returns HTTP status 204.
+        # @return Otherwise, returns the appropriate standard HTTP status
+        def show
+          if @device.nil?
+            render json: {}, status: :not_found
+            return
+          end
+
+          passes = fetch_registered_passes
+          if passes.none?
+            render json: {}, status: :no_content
+            return
+          end
+
+          render json: updatable_passes(passes).to_json
+        end
+
+        # @return If disassociation succeeds, returns HTTP status 200.
+        # @return If the request is not authorized, returns HTTP status 401.
+        # @return Otherwise, returns the appropriate standard HTTP status.
+        def destroy
+          devices = @pass.devices.where(device_id: params[:device_id],
+            pass_type_id: params[:pass_type_id])
+          if devices.any?
+            devices.delete_all
+            render json: {}, status: :ok
+          else
+            render json: {}, status: :unauthorized
+          end
+        end
+
+        private
+
+        def load_pass
+          authentication_token = request.headers["Authorization"]&.split(" ") & [1]
+          unless authentication_token.present?
+            render json: {}, status: :unauthorized
+            return
+          end
+
+          @pass = Pass.find_by(serial_number: params[:serial_number], authentication_token: authentication_token)
+          unless @pass
+            render json: {}, status: :unauthorized
+          end
+        end
+
+        def load_device
+          @device = Passkit::Device.find_by(identifier: params[:device_id])
+        end
+
+        def register_device
+          @pass.devices.create!(identifier: params[:device_id], push_token: push_token)
+        end
+
+        def fetch_registered_passes
+          passes = @device.passes
+
+          if params[:passesUpdatedSince]&.present?
+            passes.all.filter { |a| a.generator.updated_at >= Date.parse(params[:passesUpdatedSince]) }
+          else
+            passes
+          end
+        end
+
+        def updatable_passes(passes)
+          {lastUpdated: Time.zone.now, serialNumbers: passes.pluck(:serial_number)}
+        end
+
+        # TODO: add authentication_token
+        # The value is the word ApplePass, followed by a space
+        # The value is the word AndroidPass (instead of ApplePass), followed by a space
+        def authentication_token
+          ""
+        end
+
+        def push_token
+          return unless request&.body
+
+          request.body.rewind
+          json_body = JSON.parse(request.body.read)
+          json_body["pushToken"]
+        end
+      end
+    end
+  end
+end

data/app/controllers/passkit/logs_controller.rb

@@ -0,0 +1,9 @@
+module Passkit
+  class LogsController < ActionController::Base
+    layout "passkit/application"
+
+    def index
+      @logs = Passkit::Log.order(created_at: :desc).first(100)
+    end
+  end
+end

data/app/controllers/passkit/passes_controller.rb

@@ -1,24 +1,9 @@
 module Passkit
-  class PassesController  < ActionController::Base
-    skip_before_action :verify_authenticity_token
-    before_action :decrypt_payload, only: :create
+  class PassesController < ActionController::Base
+    layout "passkit/application"
 
-    def create
-      send_file(fetch_pass(@payload))
-    end
-
-    private
-
-    def decrypt_payload
-      @payload = Passkit::UrlEncrypt.decrypt(params[:payload])
-      if DateTime.parse(@payload[:valid_until]).past?
-        head :not_found
-      end
-    end
-
-    def fetch_pass(payload)
-      generator = payload[:generator_type].constantize.find(payload[:generator_id])
-      Passkit::Factory.create_pass(generator)
+    def index
+      @passes = Passkit::Pass.order(created_at: :desc).includes(:devices).first(100)
     end
   end
 end

data/app/controllers/passkit/previews_controller.rb

@@ -0,0 +1,13 @@
+module Passkit
+  class PreviewsController < ActionController::Base
+    layout "passkit/application"
+
+    def index
+    end
+
+    def show
+      builder = Passkit.configuration.available_passes[params[:class_name]]
+      send_file Factory.create_pass(builder.call, params[:class_name].constantize)
+    end
+  end
+end

data/app/mailers/passkit/example_mailer.rb

@@ -0,0 +1,8 @@
+module Passkit
+  class ExampleMailer < ActionMailer::Base
+    def example_email
+      @passkit_url_generator = Passkit::UrlGenerator.new(Passkit::ExampleStoreCard, nil)
+      mail(to: "passkit@example.com", subject: "Here is an example of a passkit email")
+    end
+  end
+end

data/{lib → app/models}/passkit/device.rb

@@ -1,9 +1,9 @@
 module Passkit
   class Device < ActiveRecord::Base
-    validates_uniqueness_of :device_identifier
+    validates_uniqueness_of :identifier
     validates_uniqueness_of :push_token
 
-    has_many :registrations
+    has_many :registrations, foreign_key: :passkit_device_id
     has_many :passes, through: :registrations
   end
 end

data/app/models/passkit/pass.rb

@@ -0,0 +1,45 @@
+module Passkit
+  class Pass < ActiveRecord::Base
+    validates_uniqueness_of :serial_number
+    validates_presence_of :klass
+
+    belongs_to :generator, polymorphic: true, optional: true
+    has_many :registrations, foreign_key: :passkit_pass_id
+    has_many :devices, through: :registrations
+
+    delegate :file_name,
+      :pass_path,
+      :language,
+      :format_version,
+      :apple_team_identifier,
+      :foreground_color,
+      :background_color,
+      :web_service_url,
+      :barcode,
+      :voided,
+      :organization_name,
+      :description,
+      :logo_text,
+      :locations,
+      :pass_type_identifier,
+      :pass_type,
+      :header_fields,
+      :primary_fields,
+      :secondary_fields,
+      :auxiliary_fields,
+      :back_fields,
+      to: :instance
+
+    before_validation on: :create do
+      self.authentication_token ||= SecureRandom.hex
+      loop do
+        self.serial_number = SecureRandom.uuid
+        break unless self.class.exists?(serial_number: serial_number)
+      end
+    end
+
+    def instance
+      @instance ||= klass.constantize.new(generator)
+    end
+  end
+end

data/app/models/passkit/registration.rb

@@ -0,0 +1,6 @@
+module Passkit
+  class Registration < ActiveRecord::Base
+    belongs_to :device, foreign_key: :passkit_device_id
+    belongs_to :pass, foreign_key: :passkit_pass_id
+  end
+end

data/app/views/layouts/passkit/application.html.erb

@@ -0,0 +1,16 @@
+<html>
+<head>
+  <title>Passkit Previews</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">
+</head>
+<body>
+
+  <%= yield %>
+
+<footer>
+  Made with ❤️ by <a href="https://github.com/sponsors/coorasse/">coorasse</a>.
+</footer>
+</body>
+</html>

data/app/views/passkit/example_mailer/example_email.html.erb

@@ -0,0 +1,15 @@
+<p>
+  Here is an example of an email message that contains a link to Download a Wallet Pass.
+</p>
+<p>
+  <a href="<%=@passkit_url_generator.ios %>">
+    <%=image_tag 'passkit/add_to_apple_wallet_en.png', style: 'width: 150px;' %>
+    Download a iOS Wallet Pass
+  </a>
+</p>
+<p>
+  <a href="<%=@passkit_url_generator.android %>">
+    <%=image_tag 'https://walletpasses.io/badges/badge_web_black_en@3x.png', style: 'width: 150px;' %>
+    Download an Android Wallet Pass
+  </a>
+</p>

data/app/views/passkit/logs/index.html.erb

@@ -0,0 +1,22 @@
+<header>
+  <h1>Passkit Logs</h1>
+  <%= render 'shared/passkit/navigation' %>
+</header>
+
+<main>
+    <h2>Last 100 log entries</h2>
+    <table>
+      <thead>
+        <th>Timestamp</th>
+        <th>Content</th>
+      </thead>
+      <tbody>
+      <% @logs.each do |log| %>
+        <tr>
+          <td><%= I18n.l(log.created_at) %></td>
+          <td><%= log.content.sub(/^\[.*\]/, '') %></td>
+        </tr>
+      <% end %>
+      </tbody>
+    </table>
+</main>

data/app/views/passkit/passes/index.html.erb

@@ -0,0 +1,32 @@
+<header>
+  <h1>Passkit Passes</h1>
+  <%= render 'shared/passkit/navigation' %>
+</header>
+
+<main>
+  <h2>Last 100 passes and registered devices</h2>
+  <table>
+    <thead>
+    <th>Created at</th>
+    <th>Generator</th>
+    <th>Pass Class</th>
+    <th>Devices</th>
+    </thead>
+    <tbody>
+    <% @passes.each do |pass| %>
+      <tr>
+        <td><%= I18n.l(pass.created_at) %></td>
+        <td><%= pass.generator.to_s %></td>
+        <td><%= pass.klass %></td>
+        <td>
+          <% pass.devices.each do |device| %>
+            <div>
+                <%= device.push_token %>
+            </div>
+          <% end %>
+        </td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+</main>

data/app/views/passkit/previews/index.html.erb

@@ -0,0 +1,21 @@
+<header>
+  <h1>Passkit Previews</h1>
+  <%= render 'shared/passkit/navigation' %>
+</header>
+<main>
+  <p>Here you can generate a Pass from the ones available. Configure your available passes with:</p>
+  <pre>
+  Passkit.configure do |config|
+    config.available_passes['Passkit::YourPass'] = -> { FactoryBot.create(:user) }
+  end
+</pre>
+  <p>Where you specify the class name as key and a function to generate a builder,
+    that will be passed used to generte the Pass</p>
+
+  <% Passkit.configuration.available_passes.each do |pass_class_name, _builder_function| %>
+    <article>
+      <h2><%= pass_class_name %></h2>
+      <%= link_to 'Generate and download', preview_path(pass_class_name) %>
+    </article>
+  <% end %>
+</main>

data/app/views/shared/passkit/_navigation.html.erb

@@ -0,0 +1,5 @@
+<nav>
+  <%=link_to 'Logs', logs_path %>
+  <%=link_to 'Passes', passes_path %>
+  <%=link_to 'Passes Previews', previews_path %>
+</nav>

data/config/routes.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
 Passkit::Engine.routes.draw do
-  resources :devices, only: [] do
-    post 'registrations/:pass_type_id/:serial_number' => 'registrations#create', as: :register
-    delete 'registrations/:pass_type_id/:serial_number' => 'registrations#destroy', as: :unregister
-    get 'registrations/:pass_type_id' => 'registrations#show', as: :registrations
+  scope :api, constraints: {pass_type_id: /.*/} do
+    scope :v1 do
+      resources :devices, only: [] do
+        post "registrations/:pass_type_id/:serial_number" => "api/v1/registrations#create", :as => :register
+        delete "registrations/:pass_type_id/:serial_number" => "api/v1/registrations#destroy", :as => :unregister
+        get "registrations/:pass_type_id" => "api/v1/registrations#show", :as => :registrations
+      end
+      get "passes/:pass_type_id/:serial_number" => "api/v1/passes#show", :as => :pass
+      get "passes/:payload", to: "api/v1/passes#create", as: :passes_api
+      post "log" => "api/v1/logs#create", :as => :log
+    end
+  end
+
+  unless Rails.env.production?
+    resources :previews, only: [:index, :show], param: :class_name
+    resources :logs, only: [:index]
+    resources :passes, only: [:index]
   end
-  get 'passes/:pass_type_id/:serial_number' => 'passes#show', as: :pass
-  get 'passes/:payload', to: 'passes#create', as: :passes
-  post 'log' => 'logs#create'
 end