monk-id 1.0.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZWZiMDQ3ZjBlYWFiNzAxMWY3ZTdiZGY0NzJhNTg4ODE2YmQwNTViNg==
+  data.tar.gz: !binary |-
+    YjNkN2EwMTFjZWZkNmRmMmY2MDdlMzllNDA1ODg4YTJiYzE4ZTM3Nw==
+SHA512:
+  metadata.gz: !binary |-
+    OWQ3YmU5MDgyZjUzOTdmYjkzYTY4NTgyOTRmMjJkOTYxNWJhMzAwZDJhM2Ex
+    NjhmMDVmMWE0ODA4ZGE4MDM4ZTkwZDEwY2UyMjdlYWVkYjRmYWQ4M2VhYjIz
+    N2JlM2QxZTJmZjliNDgzMzBiMGY2YjYyOWI0ZmRhOTgzYzZlMTE=
+  data.tar.gz: !binary |-
+    YWI3MWQyYTg5Zjk2MTcyNzZhZmM1NmU2ZTBiYzE0NTY0NzZhNGE4MDcxNjMx
+    ZmUxYzAyZjA0ZTJhZjU0NWRjNmRlMGVkNmYyNjY3NGU5Y2JmMDJmMDc2Y2E1
+    NzAwZmYwYjk4Y2E1ODI1MmM5ODdlZDBkNTRlMzk5MzY5ZDQwNjE=

data/README.md

@@ -1,35 +1,86 @@
 Monk ID Ruby
 ============
 
-Full API docs: http://monkdev.github.io/monk-id-ruby/Monk/Id.html
+[![Gem Version](https://badge.fury.io/rb/monk-id.png)](http://badge.fury.io/rb/monk-id)
 
-Add to your `Gemfile`:
+Integrate Monk ID authentication and single sign-on for apps and websites on the
+server-side.
+
+*   [Documentation](http://monkdev.github.io/monk-id-ruby/Monk/Id.html)
+
+Overview
+--------
+
+Monk ID authentication and single sign-on works in the browser by integrating
+[Monk ID JS](https://github.com/MonkDev/monk-id-js). Only being able to check
+whether a user is signed in on the client-side is limiting, however, which is
+where this library is helpful. It takes a payload from the client-side
+JavaScript and decodes it for access in your Ruby code. There is no Monk ID API
+that can be accessed on the server-side, so this library depends on client-side
+integration.
+
+### Install
+
+Add the gem to your `Gemfile` if using [Bundler](http://bundler.io):
 
 ```ruby
-gem 'monk-id', :github => 'MonkDev/monk-id-ruby', :branch => 'next'
+gem 'monk-id'
 ```
 
-For Rails and Sinatra, copy `config/monk_id.sample.yml` in this repository to
-`config/monkid.yml` in your app. This will be loaded automatically. All other
-apps need to load their config explicitly:
+```bash
+$ bundle
+```
+
+Or install manually:
+
+```bash
+$ gem install monk-id
+```
+
+### Configure
+
+Configuration is done in an external YAML file. There's a sample file in this
+repository: `config/monk_id.sample.yml`.
+
+Rails and Sinatra apps need only copy this file to `config/monk_id.yml` for it
+to be loaded automatically.
+
+All other apps need to load the file explicitly:
 
 ```ruby
 Monk::Id.load_config('/path/to/monk_id.yml', 'development')
 ```
 
-Next, load the payload:
+Remember, replace the sample values with your own, and keep the file safe as it
+contains your app secret.
+
+### Access
+
+If you have Monk ID JS configured to store the payload automatically in a cookie
+(the default), simply pass a hash-like cookies object to load the payload from:
+
+```ruby
+Monk::Id.load_payload(cookies)
+```
+
+The encoded payload can also be passed directly, which is useful if you're
+sending it in a GET/POST request instead:
 
 ```ruby
 Monk::Id.load_payload(params[:monk_id_payload])
 ```
 
-Or, if using the `cookie` option, simply pass in a hash-like cookies object:
+Loading the payload must be done before trying to access any values stored in
+the payload. In Rails, this usually means placing it in a `before_action` in
+your `ApplicationController`.
+
+Once the payload is loaded, you can ask whether the user is signed in:
 
 ```ruby
-Monk::Id.load_payload(cookies)
+Monk::Id.signed_in?
 ```
 
-Then you can access the user's ID and email:
+Or for their ID and email:
 
 ```ruby
 Monk::Id.user_id
@@ -38,3 +89,101 @@ Monk::Id.user_email
 
 `nil` is returned if the user isn't signed in or the payload can't be decoded
 and verified.
+
+Development
+-----------
+
+Start by installing the development dependencies with Bundler:
+
+```bash
+$ bundle
+```
+
+This requires all subsequent commands be prepended with `bundle exec`, which has
+been ommitted for conciseness.
+
+During development, changes must be tested manually since an automated test
+suite does not yet exist. This is best done by requiring the library locally in
+an app or website that integrates it already. There are a few ways to do this.
+
+### With Bundler
+
+Not to be confused with the fact that Bundler is used for development of this
+library, if Bundler is used in the test app or website, you can either specify a
+path to the library locally:
+
+```ruby
+gem 'monk-id', :path => '/path/to/monk-id-ruby'
+```
+
+Or configure Bundler to use a local repository instead of the GitHub repository
+(more details [in the documentation](http://bundler.io/v1.5/git.html#local)):
+
+```ruby
+gem 'monk-id', :github => 'MonkDev/monk-id-ruby', :branch => 'master'
+```
+
+```bash
+$ bundle config local.monk-id /path/to/monk-id-ruby
+```
+
+### Without Bundler
+
+If Bundler is not used, you can either build and install the gem as a system
+gem (this must be done for every change):
+
+```bash
+$ rake install
+```
+
+```ruby
+require 'monk/id'
+```
+
+Or require the library directly:
+
+```ruby
+require '/path/to/monk-id-ruby/lib/monk/id'
+```
+
+### Documentation
+
+[YARD](http://yardoc.org) is used for code documentation. During development,
+you can preview as you document by starting the YARD server:
+
+```bash
+$ yard server --reload
+```
+
+This hosts the documentation at http://localhost:8808 and automatically watches
+for changes on page refresh.
+
+The documentation can also be built to a `doc` directory (that is ignored by
+git):
+
+```bash
+$ yard
+```
+
+Deployment
+----------
+
+[gem-release](https://github.com/svenfuchs/gem-release) is used to
+
+1.  bump the version in `lib/monk/id/version.rb`,
+2.  tag and push the release to GitHub,
+3.  and release to [RubyGems](https://rubygems.org).
+
+These steps can be executed individually, but it's easiest to do all at once:
+
+```bash
+$ gem bump --version major|minor|patch --tag --release
+```
+
+Be sure to choose the correct version by following
+[Semantic Versioning](http://semver.org).
+
+### Publish Documentation
+
+After releasing a new version, the documentation must be manually built and
+published to the `gh-pages` branch.

data/lib/monk/id.rb

@@ -3,6 +3,8 @@ require 'json'
 require 'openssl'
 require 'yaml'
 
+require 'monk/id/version'
+
 # Global Monk namespace.
 module Monk
   # Integrate Monk ID on the server-side by accessing payloads from the
@@ -23,23 +25,16 @@ module Monk
       # {CONFIG_FILE}, as it's loaded automatically.
       #
       # @param  path [String] Path of YAML config file to load. Leave `nil` to
-      #         read from environment's `MONK_ID_CONFIG` value.
+      #         read from environment (`MONK_ID_CONFIG` variable, Rails,
+      #         Sinatra).
       # @param  environment [String] Environment section to use. Leave `nil` to
-      #         read from environment's `MONK_ID_ENV` value. Defaults to
-      #         `development`.
+      #         read from environment (`MONK_ID_ENV` variable, Rails, Sinatra).
+      #         Defaults to `development`.
       # @raise  [StandardError] If the file doesn't exist or can't be read.
       # @return [Hash<String>] Loaded config values.
       def load_config(path = nil, environment = nil)
-        if defined? Rails
-          path ||= File.join(Rails.root, CONFIG_FILE)
-          environment ||= Rails.env
-        elsif defined? Sinatra
-          path ||= File.join(Sinatra::Application.settings.root, CONFIG_FILE)
-          environment ||= Sinatra::Application.settings.environment.to_s
-        else
-          path ||= ENV['MONK_ID_CONFIG']
-          environment ||= ENV['MONK_ID_ENV'] || 'development'
-        end
+        path ||= config_path_from_environment
+        environment ||= config_environment
 
         config = YAML.load_file(path)[environment]
 
@@ -116,6 +111,37 @@ module Monk
       # Loaded payload.
       @@payload = nil
 
+      # Get the path to the config file from the environment. Supports `ENV`
+      # variable, Rails, and Sinatra.
+      # 
+      # @return [String] Path to the config file.
+      # @return [nil] If not set by the environment.
+      def config_path_from_environment
+        if ENV['MONK_ID_CONFIG']
+          ENV['MONK_ID_CONFIG']
+        elsif defined? Rails
+          File.join(Rails.root, CONFIG_FILE)
+        elsif defined? Sinatra
+          File.join(Sinatra::Application.settings.root, CONFIG_FILE)
+        end
+      end
+
+      # Get the environment to load within the config. Supports `ENV` variable,
+      # Rails, and Sinatra. Defaults to `development` if none specify.
+      # 
+      # @return [String] Environment name.
+      def config_environment
+        if ENV['MONK_ID_ENV']
+          ENV['MONK_ID_ENV']
+        elsif defined? Rails
+          Rails.env
+        elsif defined? Sinatra
+          Sinatra::Application.settings.environment.to_s
+        else
+          'development'
+        end
+      end
+
       # Verify that a config has all the required values.
       #
       # @param  config [Hash<String>] Config values.

data/lib/monk/id/version.rb

@@ -1,6 +1,6 @@
 module Monk
   module Id
     # Current version of the library.
-    VERSION = '1.0.0'.freeze
+    VERSION = '1.1.0'.freeze
   end
 end

data/monk-id.gemspec

@@ -8,17 +8,19 @@ Gem::Specification.new do |spec|
   spec.version       = Monk::Id::VERSION.dup
   spec.authors       = ['Monk Development, Inc.']
   spec.email         = ['support@monkdevelopment.com']
-  spec.description   = 'Integrate Monk ID on the server-side by accessing payloads from the client-side JavaScript.'
-  spec.summary       = spec.description
+  spec.summary       = 'Integrate Monk ID authentication and single sign-on for apps and websites on the server-side.'
+  spec.description   = spec.summary
   spec.homepage      = 'https://github.com/MonkDev/monk-id-ruby'
   spec.license       = 'MIT'
 
-  spec.files         = `git ls-files`.split($/)
+  spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.3'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'gem-release', '~> 0.7'
+  spec.add_development_dependency 'rake', '~> 10.1'
+  spec.add_development_dependency 'yard', '~> 0.8'
+  spec.add_development_dependency 'redcarpet', '~> 3.1'
 end

metadata

@@ -1,66 +1,87 @@
 --- !ruby/object:Gem::Specification
 name: monk-id
 version: !ruby/object:Gem::Version
-  version: 1.0.0
-  prerelease: 
+  version: 1.1.0
 platform: ruby
 authors:
 - Monk Development, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-11 00:00:00.000000000 Z
+date: 2014-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: gem-release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.1'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
-description: Integrate Monk ID on the server-side by accessing payloads from the client-side
-  JavaScript.
+        version: '3.1'
+description: Integrate Monk ID authentication and single sign-on for apps and websites
+  on the server-side.
 email:
 - support@monkdevelopment.com
 executables: []
@@ -79,28 +100,27 @@ files:
 homepage: https://github.com/MonkDev/monk-id-ruby
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 2.2.2
 signing_key: 
-specification_version: 3
-summary: Integrate Monk ID on the server-side by accessing payloads from the client-side
-  JavaScript.
+specification_version: 4
+summary: Integrate Monk ID authentication and single sign-on for apps and websites
+  on the server-side.
 test_files: []
 has_rdoc: