mapkit_token 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45bea3e3d390b755069255b64c3d7feb217d8c724db38c3030403d1449cd01d9
-  data.tar.gz: ab38b4f43b735ce4ecd7ddca3d1a1a1453f6430489c85d1c2381b5ec71302413
+  metadata.gz: '0366869d9c259cd6a25c28915b9f71b851b6a283bd881802f6af2b8e7c8a805c'
+  data.tar.gz: 29e882698f549c01f296d9d77ba3f96ea4d7905eaeca113fd57e66c2d9a3bb9d
 SHA512:
-  metadata.gz: 3cae35f9190898e2101da404c1deeb600fa72d2a9d9d11a39b7c1fec7a7270bd2d78bcdace8156c00b5e11ed6a725e1d3094a595c4692bb14e49c29fe36e720f
-  data.tar.gz: d822fe17f5db923ce272321a6ecee1a403337f46b1e45ad24517b62e2a50c68823fa3bd75fb614b424a13614e38d69aa5dff68e67b919d75d591d63f711ed9e5
+  metadata.gz: e80969e65ab3322b4d9e2712333f995bd1ec46fef965c89af2bda595e2fb6575c04ffec16f18c2c398066fea59c97d0a7cd361c078dc2136c25b17d145acb828
+  data.tar.gz: dc34fe4c6b9210ce2f0a4849cd44e94f246c65c0e054443bc87965f5a6c5b4fce157e9c47ae5bafe1324f4ecd0410e569e75d2331d3443441884fce4c48a5425

data/README.md

@@ -24,30 +24,86 @@ Before you can use this gem, you need a Maps Identifer (i.e., Maps ID) and priva
 
 [Creating a Maps Identifier and a Private Key](https://developer.apple.com/documentation/mapkitjs/creating_a_maps_identifier_and_a_private_key)
 
-Add your AuthKey to your application folder, and make sure you have these pieces of information:
+You need three pieces of information: the private key, the MapKit JS Key ID, and your Apple Developer Team ID.
 
-- Path to AuthKey
-- MapKit JS Key ID
-- Apple Developer Team ID
+You can store them in an initializer, in your Rails credentials, or in environment variables. Use whichever fits the machine your application runs on. The gem checks those places in that order for each setting.
 
-Edit your application credentials:
+The key itself can be given either as the contents of the `.p8` file or as a path to it. The gem looks for the contents in all three places before it looks for a path. This means that if a server sets the key contents in its environment, that value is used even when the credentials point to a file that doesn't exist on that server.
+
+### Option 1: Path to the key file in credentials
+
+Add the `.p8` file from Apple to your application folder, then edit your credentials:
 
     $ EDITOR=vim rails credentials:edit
 
-In case you have different AuthKey files for your different environments, edit your environment credentials separately:
+```yaml
+mapkit:
+  auth_key_path: AuthKey_XXXXXXXXXX.p8
+  auth_key_id: XXXXXXXXXX
+  apple_team_id: XXXXXXXXXX
+```
+
+A relative path is resolved from `Rails.root`. An absolute path is used as is. If you have different AuthKey files for different environments, edit each environment's credentials separately:
 
     $ EDITOR=vim rails credentials:edit --environment development
 
-Add your credentials:
+The gem provides legacy support for Rails secrets, so if your app uses Rails 4.1 through 5.1, you can store the same information in `/config/secrets.yml` and it will just work.
+
+### Option 2: Key contents in credentials
+
+If shipping the `.p8` file is inconvenient (for example, in a container image or on a server built only from the repository), you can paste the contents of the file into your credentials instead:
 
 ```yaml
 mapkit:
-  auth_key_path: AuthKey_XXXXXXXXXX.p8
+  auth_key: |
+    -----BEGIN PRIVATE KEY-----
+    MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQg...
+    -----END PRIVATE KEY-----
   auth_key_id: XXXXXXXXXX
   apple_team_id: XXXXXXXXXX
 ```
 
-After reloading your application, it will have a new endpoint `/mapkit_token` that returns JWTs that are valid for 30 minutes. The application's hostname is added to the JWT payload to specify that the tokens only can used by the application itself. 
+### Option 3: Environment variables
+
+You can also set everything with environment variables. This works well for deployments that keep secrets outside the repository:
+
+```sh
+MAPKIT_AUTH_KEY_ID=XXXXXXXXXX
+MAPKIT_APPLE_TEAM_ID=XXXXXXXXXX
+
+# Either the contents of the .p8 file...
+MAPKIT_AUTH_KEY="$(cat AuthKey_XXXXXXXXXX.p8)"
+
+# ...or the path to it, if the file is on the machine
+MAPKIT_AUTH_KEY_PATH=/etc/mapkit/AuthKey_XXXXXXXXXX.p8
+```
+
+The key spans several lines, and some tools can't set an environment variable that contains newlines. For those cases, `MAPKIT_AUTH_KEY` also accepts two single-line formats:
+
+- The key with each newline written as `\n`
+- The whole file encoded as base64 (`base64 -w0 AuthKey_XXXXXXXXXX.p8`)
+
+### Option 4: An initializer
+
+If you'd rather configure the gem in code (for example, to read the key from a secrets manager or from environment variables with your own names), create `config/initializers/mapkit_token.rb`:
+
+```ruby
+MapkitToken.setup do |config|
+  config.auth_key = Vault.read("mapkit").data[:p8]
+  config.auth_key_id = ENV.fetch("MY_MAPKIT_KEY_ID")
+  config.apple_team_id = ENV.fetch("MY_APPLE_TEAM_ID")
+end
+```
+
+You can also set `config.app_root` here to resolve a relative `auth_key_path` from a folder other than `Rails.root`.
+
+### Missing settings
+
+If a setting can't be found, the gem raises `MapkitToken::ConfigurationError` with a message that says what's missing and where you can set it. You get this clear error instead of a confusing failure later on from an unreadable key.
+
+To check whether a key is configured without raising an error, call `MapkitToken.config.auth_key?`. This is useful if you want to skip rendering a map when no token is available.
+
+After reloading your application, it will have a new endpoint `/mapkit_token` that returns JWTs that are valid for 30 minutes. The application's hostname is added to the JWT payload to specify that the tokens only can used by the application itself.
 
 Use the endpoint for the `authorizationCallback` function that MapKit JS calls whenever it detects that a new token is needed.
 

data/app/controllers/mapkit_token/mapkit_token_controller.rb

@@ -1,28 +1,23 @@
 module MapkitToken
   class MapkitTokenController < ApplicationController
 
-    def mapkit
-      Rails.application.credentials.mapkit
-    end
-
-    def auth_key
-      File.read(mapkit[:auth_key_path])
+    def show
+      render plain: Mapkit.token.generate(
+        auth_key: mapkit.auth_key,
+        auth_key_id: mapkit.auth_key_id,
+        apple_team_id: mapkit.apple_team_id,
+        base_url: base_url
+      )
     end
 
-    def auth_key_id
-      mapkit[:auth_key_id]
-    end
+    private
 
-    def apple_team_id
-      mapkit[:apple_team_id]
+    def mapkit
+      MapkitToken.config
     end
 
     def base_url
       request.protocol + request.host
     end
-
-    def show
-      render plain: Mapkit.token.generate(auth_key: auth_key, auth_key_id: auth_key_id, apple_team_id: apple_team_id, base_url: base_url)
-    end
   end
 end

data/lib/mapkit_token/config.rb

@@ -0,0 +1,138 @@
+require "pathname"
+
+module MapkitToken
+  class ConfigurationError < StandardError; end
+
+  class Config
+    ENV_NAMES = {
+      :auth_key      => "MAPKIT_AUTH_KEY",
+      :auth_key_path => "MAPKIT_AUTH_KEY_PATH",
+      :auth_key_id   => "MAPKIT_AUTH_KEY_ID",
+      :apple_team_id => "MAPKIT_APPLE_TEAM_ID"
+    }.freeze
+
+    PEM_MARKER = "-----BEGIN".freeze
+
+    def auth_key
+      carried = setting(:auth_key)
+      return pem(carried) if carried.present?
+
+      path = auth_key_path
+      if path.blank?
+        raise ConfigurationError, explain("No MapKit auth key. Set the contents " \
+          "of the .p8 with #{places(:auth_key)}, or a path to it with " \
+          "#{places(:auth_key_path)}.")
+      end
+
+      file = expand_path(path)
+      unless File.exist?(file)
+        raise ConfigurationError, "MapKit auth key file not found at #{file}"
+      end
+      pem(File.read(file))
+    end
+
+    def auth_key_path
+      setting(:auth_key_path)
+    end
+
+    def auth_key_id
+      require_setting(:auth_key_id, "No MapKit key id.")
+    end
+
+    def apple_team_id
+      require_setting(:apple_team_id, "No Apple team id.")
+    end
+
+    def auth_key?
+      auth_key
+      true
+    rescue ConfigurationError
+      false
+    end
+
+    private
+
+    def setting(name)
+      from_initializer(name) || from_credentials(name) || from_env(name)
+    end
+
+    def require_setting(name, message)
+      value = setting(name)
+      if value.blank?
+        raise ConfigurationError, explain("#{message} Set it with #{places(name)}.")
+      end
+      value
+    end
+
+    def places(name)
+      "config.#{name} in MapkitToken.setup, `mapkit: #{name}` in the " \
+        "credentials, or #{ENV_NAMES.fetch(name)}"
+    end
+
+    # A credentials file that can't be decrypted reads as empty, so the
+    # environment still gets its turn; say so when nothing is found there.
+    def explain(message)
+      return message if @credentials_error.nil?
+      "#{message} The credentials could not be read " \
+        "(#{@credentials_error.class}), so any MapKit settings in them were skipped."
+    end
+
+    def from_initializer(name)
+      MapkitToken.public_send(name).presence
+    end
+
+    def from_credentials(name)
+      credentials[name].presence
+    end
+
+    def from_env(name)
+      ENV[ENV_NAMES.fetch(name)].presence
+    end
+
+    def credentials
+      store = credentials_store
+      return {} if store.nil?
+      store.respond_to?(:to_h) ? store.to_h.symbolize_keys : {}
+    rescue StandardError => e
+      @credentials_error = e
+      {}
+    end
+
+    def credentials_store
+      app = application
+      return nil if app.nil?
+
+      if app.respond_to?(:credentials)
+        app.credentials.mapkit
+      elsif app.respond_to?(:secrets)
+        app.secrets.mapkit
+      end
+    end
+
+    def application
+      return nil unless defined?(Rails) && Rails.respond_to?(:application)
+      Rails.application
+    end
+
+    def app_root
+      MapkitToken.app_root || (application && Rails.root) || Dir.pwd
+    end
+
+    def expand_path(path)
+      pathname = Pathname.new(path.to_s)
+      pathname.absolute? ? pathname.to_s : File.join(app_root.to_s, pathname.to_s)
+    end
+
+    def pem(value)
+      key = value.to_s.strip.gsub('\n', "\n")
+      return terminate(key) if key.include?(PEM_MARKER)
+
+      decoded = key.unpack1("m").force_encoding(Encoding::UTF_8)
+      decoded.include?(PEM_MARKER) ? terminate(decoded) : key
+    end
+
+    def terminate(key)
+      key.end_with?("\n") ? key : key + "\n"
+    end
+  end
+end

data/lib/mapkit_token/engine.rb

@@ -1,3 +1,5 @@
+require "rails/engine"
+
 module MapkitToken
   class Engine < Rails::Engine
   end

data/lib/mapkit_token/version.rb

@@ -1,3 +1,3 @@
 module MapkitToken
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/mapkit_token.rb

@@ -1,15 +1,23 @@
 require "active_support/all"
 require "mapkit_token/version"
+require "mapkit_token/config"
 require "mapkit_token/app/models/mapkit.rb"
 require "jwt"
 
 module MapkitToken
   mattr_accessor :app_root
+  mattr_accessor :auth_key
+  mattr_accessor :auth_key_path
+  mattr_accessor :auth_key_id
+  mattr_accessor :apple_team_id
 
   def self.setup
     yield self
   end
+
+  def self.config
+    Config.new
+  end
 end
 
 require "mapkit_token/engine"
-

data/mapkit_token.gemspec

@@ -19,8 +19,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", ">= 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
 
   spec.add_dependency "activesupport"

metadata

@@ -1,43 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: mapkit_token
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Michael Edlund
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -94,7 +79,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
 email:
 - medlund@mac.com
 executables: []
@@ -114,13 +98,13 @@ files:
 - config/routes.rb
 - lib/mapkit_token.rb
 - lib/mapkit_token/app/models/mapkit.rb
+- lib/mapkit_token/config.rb
 - lib/mapkit_token/engine.rb
 - lib/mapkit_token/version.rb
 - mapkit_token.gemspec
 homepage: https://github.com/arcticleo/mapkit_token
 licenses: []
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -135,8 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 4.0.20
 specification_version: 4
 summary: MapKit JS token endpoint provider.
 test_files: []