From 5b06b72b3440d9ae746774024fa6f5328dda1ae4 Mon Sep 17 00:00:00 2001 From: Tony Arcieri Date: Sat, 16 Jan 2016 11:20:47 -0800 Subject: [PATCH] Initial commit --- .gitignore | 9 ++ .rspec | 4 + .rubocop.yml | 27 ++++++ .travis.yml | 4 + Gemfile | 13 +++ LICENSE.txt | 20 ++++ README.md | 162 +++++++++++++++++++++++++++++++ Rakefile | 8 ++ bin/console | 14 +++ bin/setup | 8 ++ boulangerie-rails.gemspec | 30 ++++++ lib/boulangerie/rails.rb | 7 ++ lib/boulangerie/rails/version.rb | 6 ++ spec/boulangerie/rails_spec.rb | 5 + spec/spec_helper.rb | 4 + 15 files changed, 321 insertions(+) create mode 100644 .gitignore create mode 100644 .rspec create mode 100644 .rubocop.yml create mode 100644 .travis.yml create mode 100644 Gemfile create mode 100644 LICENSE.txt create mode 100644 README.md create mode 100644 Rakefile create mode 100755 bin/console create mode 100755 bin/setup create mode 100644 boulangerie-rails.gemspec create mode 100644 lib/boulangerie/rails.rb create mode 100644 lib/boulangerie/rails/version.rb create mode 100644 spec/boulangerie/rails_spec.rb create mode 100644 spec/spec_helper.rb diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0cb6eeb --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +/.bundle/ +/.yardoc +/Gemfile.lock +/_yardoc/ +/coverage/ +/doc/ +/pkg/ +/spec/reports/ +/tmp/ diff --git a/.rspec b/.rspec new file mode 100644 index 0000000..ce9d5ff --- /dev/null +++ b/.rspec @@ -0,0 +1,4 @@ +--color +--format documentation +--order random +--require spec_helper diff --git a/.rubocop.yml b/.rubocop.yml new file mode 100644 index 0000000..e4123b7 --- /dev/null +++ b/.rubocop.yml @@ -0,0 +1,27 @@ +AllCops: + DisplayCopNames: true + +LineLength: + Max: 100 + +Style/StringLiterals: + EnforcedStyle: double_quotes + +Style/ClassAndModuleChildren: + Enabled: false + +Style/SpaceAroundOperators: + Enabled: false + +Metrics/MethodLength: + CountComments: false + Max: 50 + +Metrics/AbcSize: + Enabled: false + +Metrics/CyclomaticComplexity: + Max: 15 + +Metrics/PerceivedComplexity: + Max: 15 diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..bed6e27 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,4 @@ +language: ruby +rvm: + - 2.3.0 +before_install: gem install bundler -v 1.11.2 diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..aa3842e --- /dev/null +++ b/Gemfile @@ -0,0 +1,13 @@ +source "https://rubygems.org" + +gemspec + +group :development do + gem "guard-rspec" +end + +group :test do + gem "rspec" + gem "rubocop", "0.36.0" + gem "coveralls", require: false +end diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..396bd3a --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,20 @@ +Copyright (c) 2016 Tony Arcieri + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c56ef97 --- /dev/null +++ b/README.md @@ -0,0 +1,162 @@ +![Boulangerie](https://raw.githubusercontent.com/cryptosphere/boulangerie/master/boulangerie.png) +for Rails! +========== +[![Gem Version](https://badge.fury.io/rb/boulangerie-rails.svg)](http://rubygems.org/gems/boulangerie-rails) +[![Build Status](https://travis-ci.org/cryptosphere/boulangerie-rails.svg)](https://travis-ci.org/cryptosphere/boulangerie-rails) +[![Code Climate](https://codeclimate.com/github/cryptosphere/boulangerie-rails/badges/gpa.svg)](https://codeclimate.com/github/cryptosphere/boulangerie-rails) +[![Coverage Status](https://coveralls.io/repos/cryptosphere/boulangerie-rails/badge.svg?branch=master&service=github)](https://coveralls.io/github/cryptosphere/boulangerie-rails?branch=master) +[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cryptosphere/boulangerie-rails/master/LICENSE.txt) + +[Boulangerie] is a Ruby gem for building authorization systems using +[Macaroons](http://macaroons.io), a better kind of cookie. + +[Boulangerie]: https://github.com/cryptosphere/boulangerie + +## Installation + +boulangerie-rails can be used with Rails 4.1+. + +Add this line to your application's Gemfile: + +```ruby +gem 'boulangerie-rails' +``` + +And then execute: + + $ bundle + +Or install it yourself as: + + $ gem install boulangerie-rails + +## Usage + +Add the following to `config/initializers/boulangerie.rb`: + +```ruby +Boulangerie.setup( + schema: Rails.root.join("config/boulangerie_schema.yml"), + keys: Rails.application.secrets.boulangerie_keys + key_id: "key1" + location: "https://mycoolsite.com" +) +``` + +You will also need to edit `config/secrets.yml` and add the following to +your respective environments (example given for development): + +```yaml +development: + secret_key_base: DEADBEEFDEADBEEFDEADBEEF[...] + boulangerie_keys: + key0: "1b942ba242e9d39ce838d03652091695eb1fef93d35d9454498ca970a8827e8f" + key1: "7efc8f72d159ce31a4b2c8db6281bf8d91a2f2778d4d0062f80b977ea43a8ec4" +``` + +The `boulangerie_keys` hash contains a "keyring" of keys which can be used to +create or verify Macaroons. + +To generate random keys, use the `Boulangerie::Keyring.generate_key` method, +which you can call from `irb` or `pry`: + +``` +[1] pry(main)> require 'boulangerie' +=> true +[2] pry(main)> Boulangerie::Keyring.generate_key +=> "1b942ba242e9d39ce838d03652091695eb1fef93d35d9454498ca970a8827e8f" +``` + +The names of the keys (e.g. `key0`, `key1`) are arbitrary, but all new Macaroons +will use the key whose ID was passed in as the `key_id` option to +`Boulangerie#initialize`. This allows for key rotation, i.e. periodically you can +add a new key, and Macaroons minted under an old key will still verify. + +Rotating keys is good security practice and you should definitely take advantage of it. + +You'll also need to create a `config/boulangerie_schema.yml` file that +contains the schema for your Macaroons. Here is a basic schema that will +add `not-before` and `expires` timestamp assertions on your Macaroons: + +```yaml +--- +schema-id: ee6da70e5ba01fec +predicates: + v0: + not-before: DateTime + expires: DateTime +``` + +A `schema-id` is a 64-bit random number. This is used to identify a schema +uniquely within your system regardless of what you decide to name or rename +the schema file. + +You can generate a schema ID via `irb` or `pry`: + +``` +[1] pry(main)> require 'boulangerie' +=> true +[2] pry(main)> Boulangerie::Schema.create_schema_id +=> "ee6da70e5ba01fec" +``` + +A schema-id can also be any 64-bit random number serialized as hex which +is unique to your app/infrastructure. + +This schema includes two *caveats*: an expiration date and a creation time, +before which the Macaroon is not considered valid. +The predicate matchers for these particular caveats are built into +Boulangerie, but you can extend it with your own. + +To create a Macaroon, we'll need to call the `#bake` method. The following +will create a new Macaroon and set it as the "my_macaroon" cookie: + +```ruby +class AuthenticationController < ApplicationController + # Perform some kind of authentication ritual here + before_action :check_credentials, :only => :authenticate + + def authenticate + expires_at = 24.hours.from_now + + cookie = Boulangerie.bake(caveats: { + expires: Time.now, + not_before: expires_at + }) + + cookies[:my_macaroon] = { + value: cookie, + expires: expires_at, + secure: true, + httponly: true + } + end +``` + +Finally, to actually use Macaroons to make authorization decisions, we need +to configure Boulangerie in a given controller: + +```ruby +class MyController < ApplicationController + authorize_with_boulangerie :cookie => :my_macaroon +end +``` + +## Supported Ruby Versions + +This library supports and is tested against the following Ruby versions: + +* Ruby (MRI) 2.0, 2.1, 2.2, 2.3 +* JRuby 9000 + +## Contributing + +* Fork this repository on GitHub +* Make your changes and send us a pull request +* If we like them we'll merge them +* If we've accepted a patch, feel free to ask for commit access + +## License + +Copyright (c) 2016 Tony Arcieri. Distributed under the MIT License. +See LICENSE.txt for further details. diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..4c11af7 --- /dev/null +++ b/Rakefile @@ -0,0 +1,8 @@ +require "bundler/gem_tasks" +require "rspec/core/rake_task" +require "rubocop/rake_task" + +RSpec::Core::RakeTask.new(:spec) +RuboCop::RakeTask.new + +task default: %w(spec rubocop) diff --git a/bin/console b/bin/console new file mode 100755 index 0000000..f8d097a --- /dev/null +++ b/bin/console @@ -0,0 +1,14 @@ +#!/usr/bin/env ruby + +require "bundler/setup" +require "boulangerie/rails" + +# You can add fixtures and/or initialization code here to make experimenting +# with your gem easier. You can also use a different console, if you like. + +# (If you use this, don't forget to add pry to your Gemfile!) +# require "pry" +# Pry.start + +require "irb" +IRB.start diff --git a/bin/setup b/bin/setup new file mode 100755 index 0000000..dce67d8 --- /dev/null +++ b/bin/setup @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +IFS=$'\n\t' +set -vx + +bundle install + +# Do any other automated setup that you need to do here diff --git a/boulangerie-rails.gemspec b/boulangerie-rails.gemspec new file mode 100644 index 0000000..4a277b8 --- /dev/null +++ b/boulangerie-rails.gemspec @@ -0,0 +1,30 @@ +# coding: utf-8 +lib = File.expand_path("../lib", __FILE__) +$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) +require "boulangerie/rails/version" + +Gem::Specification.new do |spec| + spec.name = "boulangerie-rails" + spec.version = Boulangerie::Rails::VERSION + spec.authors = ["Tony Arcieri"] + spec.email = ["bascule@gmail.com"] + + spec.licenses = ["MIT"] + spec.homepage = "https://github.com/cryptosphere/boulangerie-rails" + spec.summary = "Rails support creating and verifying Macaroons with Boulangerie" + spec.description = <<-DESCRIPTION.strip.gsub(/\s+/, " ") + Boulangerie provides schemas, creation, and verification for the + Macaroons bearer credential format. This gem contains support for + using Boulangerie with Ruby on Rails. + DESCRIPTION + + spec.files = `git ls-files`.split($INPUT_RECORD_SEPARATOR) + spec.bindir = "exe" + spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) } + spec.require_paths = ["lib"] + spec.required_ruby_version = ">= 2.0.0" + + spec.add_runtime_dependency "boulangerie" + + spec.add_development_dependency "rake", "~> 10.0" +end diff --git a/lib/boulangerie/rails.rb b/lib/boulangerie/rails.rb new file mode 100644 index 0000000..04838fd --- /dev/null +++ b/lib/boulangerie/rails.rb @@ -0,0 +1,7 @@ +require "boulangerie/rails/version" + +module Boulangerie + # Ruby on Rails support for Boulangerie + module Rails + end +end diff --git a/lib/boulangerie/rails/version.rb b/lib/boulangerie/rails/version.rb new file mode 100644 index 0000000..a1de26c --- /dev/null +++ b/lib/boulangerie/rails/version.rb @@ -0,0 +1,6 @@ +# frozen_string_literal: true +module Boulangerie + module Rails + VERSION = "0.1.0".freeze + end +end diff --git a/spec/boulangerie/rails_spec.rb b/spec/boulangerie/rails_spec.rb new file mode 100644 index 0000000..4f8ff11 --- /dev/null +++ b/spec/boulangerie/rails_spec.rb @@ -0,0 +1,5 @@ +RSpec.describe Boulangerie::Rails do + it "has a version number" do + expect(Boulangerie::Rails::VERSION).not_to be nil + end +end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb new file mode 100644 index 0000000..c61083f --- /dev/null +++ b/spec/spec_helper.rb @@ -0,0 +1,4 @@ +$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__) +require "boulangerie/rails" + +RSpec.configure(&:disable_monkey_patching!)