rails-auth 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a492a2d3e2769b62746079b9c9d0d56fa13d9c56
-  data.tar.gz: 6eda7789839d1bb66b642b3c6af8f3ad213f98d9
+  metadata.gz: 7f4c0d9519675ef1b560bbc2cc2ef0dcc2b9b178
+  data.tar.gz: 2cd1b6f0f0f2462db7ab4bd280f1c54dc6bff513
 SHA512:
-  metadata.gz: ad6c4c9707ff5067b0e16f2e78f5afd66602b954a828e1a346128c318c5eeff4fdc2da755e3144a5b92c29f4063aff9c1e2645dad1bd420bb34edb08442ffe88
-  data.tar.gz: fe5328588172103e3ef15343dfef43b83261db496830375394a5d0151af5f939e39ce5514db5b0e474ff8cdc861a6ab8ef9137d628655f2034ede34d5bf987bf
+  metadata.gz: 91b47228828b5f448effd6e5b03d0e141b35253a388823ec5fc10ef069f9a86cbff3c7d84efa589ed513da31e1528e176671deff7fe743b7b6ad3f7121d9d7e0
+  data.tar.gz: eaaa0f23d01a3a2efcdd0c4baf65f3f6259a86b9825d10ccd96431d80529eae395f8444cf8881fb799d63a09d682ebccaf4f627b0f0bc2b77c997ce01dda96f4

data/.travis.yml

@@ -1,12 +1,16 @@
 language: ruby
 sudo: false
 
+before_install:
+  - gem install bundler
+
 rvm:
   - 2.0.0
   - 2.1.8
   - 2.2.4
   - 2.3.0
-  - jruby-9.0.4.0
-
 matrix:
+  include:
+    - rvm: jruby-9.0.4.0
+      env: JRUBY_OPTS="--debug" # for simplecov
   fast_finish: true

data/BUG-BOUNTY.md

@@ -0,0 +1,9 @@
+Break me and win a prize!
+=========================
+
+Square recognizes the important contributions the security research community
+can make. We therefore encourage reporting security issues with the code
+contained in this repository.
+
+If you believe you have discovered a security vulnerability, please follow the
+guidelines at https://hackerone.com/square-open-source

data/CHANGES.md

@@ -0,0 +1,23 @@
+### 0.1.0 (2016-02-10)
+
+* [#6](https://github.com/square/rails-auth/pull/6):
+  Rename principals to credentials and Rails::Auth::X509::Principals to
+  Rails::Auth::X509::Certificates.
+  ([@tarcieri])
+
+* [#5](https://github.com/square/rails-auth/pull/5):
+  Add Rails::Auth::ErrorPage::Middleware.
+  ([@tarcieri])
+
+### 0.0.1 (2016-01-26)
+
+* [#1](https://github.com/square/rails-auth/pull/1):
+  Initial implementation.
+  ([@tarcieri])
+
+### 0.0.0 (2016-01-04)
+
+* Vaporware release to claim the "rails-auth" gem name
+
+
+[@tarcieri]: https://github.com/tarcieri

data/Gemfile

@@ -7,6 +7,7 @@ end
 group :test do
   gem "rspec"
   gem "rubocop", "0.36.0"
+  gem "coveralls", require: false
   gem "certificate_authority", require: false
 end
 

data/README.md

@@ -1,4 +1,10 @@
-# Rails::Auth
+Rails::Auth
+===========
+[![Gem Version](https://badge.fury.io/rb/rails-auth.svg)](http://rubygems.org/gems/rails-auth)
+[![Build Status](https://travis-ci.org/square/rails-auth.svg?branch=master)](https://travis-ci.org/square/rails-auth)
+[![Code Climate](https://codeclimate.com/github/square/rails-auth/badges/gpa.svg)](https://codeclimate.com/github/square/rails-auth)
+[![Coverage Status](https://coveralls.io/repos/github/square/rails-auth/badge.svg?branch=master)](https://coveralls.io/github/square/rails-auth?branch=master)
+[![Apache 2 licensed](https://img.shields.io/badge/license-Apache2-blue.svg)](https://github.com/square/rails-auth/blob/master/LICENSE)
 
 Modular resource-based authentication and authorization for Rails/Rack
 
@@ -7,8 +13,8 @@ Modular resource-based authentication and authorization for Rails/Rack
 Rails::Auth is a flexible library designed for both authentication (AuthN) and
 authorization (AuthZ) using Rack Middleware. It splits the AuthN and AuthZ
 steps into separate middleware classes, using AuthN middleware to first verify
-request client identities, or "principals", then authorizing the request
-via separate AuthZ middleware that consumes these principals, e.g. access
+credentials (such as X.509 certificates or cookies), then authorizing the request
+via separate AuthZ middleware that consumes these credentials, e.g. access
 control lists (ACLs).
 
 Rails::Auth can be used to authenticate and authorize end users using browser
@@ -39,7 +45,7 @@ middleware for your app.
 Rails::Auth ships with the following middleware:
 
 * **AuthN**: `Rails::Auth::X509::Middleware`: support for authenticating
-  principals by their SSL/TLS client certificates.
+  clients by their SSL/TLS client certificates.
 * **AuthZ**: `Rails::Auth::ACL::Middleware`: support for authorizing requests
   using Access Control Lists (ACLs).
 
@@ -104,7 +110,7 @@ app = MyRackApp.new
 
 acl = Rails::Auth::ACL.from_yaml(
   File.read("/path/to/my/acl.yaml"),
-  matchers: { allow_claims: MyClaimsPredicate }
+  matchers: { allow_claims: MyClaimsMatcher }
 )
 
 acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)
@@ -127,14 +133,14 @@ object from the ACL definition is passed to the class's `#initialize` method.
 Here is an example of a simple custom predicate matcher:
 
 ```ruby
-class MyClaimsPredicate
+class MyClaimsMatcher
   def initialize(options)
     @options = options
   end
 
   def match(env)
-    claims = Rails::Auth.principals(env)["claims"]
-    return false unless principal
+    claims = Rails::Auth.credentials(env)["claims"]
+    return false unless credential
 
     @options["groups"].any? { |group| claims["groups"].include?(group) }
   end
@@ -223,9 +229,9 @@ certificates:
 cert_filters: { 'X-SSL-Client-Cert' => proc { |pem| OpenSSL::X509::Certificate.new(pem) } }
 ```
 
-When certificates are recognized and verified, an `Rails::Auth::X509::Principal`
-object will be added to the Rack environment under `env["rails-auth.principals"]["x509"]`.
-This middleware will never add any certificate to the environment's principals
+When certificates are recognized and verified, a `Rails::Auth::X509::Certificate`
+object will be added to the Rack environment under `env["rails-auth.credentials"]["x509"]`.
+This middleware will never add any certificate to the environment's credentials
 that hasn't been verified against the configured CA bundle.
 
 ## RSpec integration
@@ -243,7 +249,7 @@ Below is an example of how to write an ACL spec:
 
 ```ruby
 RSpec.describe "example_acl.yml", acl_spec: true do
-  let(:example_principals) { x509_principal_hash(ou: "ponycopter") }
+  let(:example_credentials) { x509_certificate_hash(ou: "ponycopter") }
 
   subject do
     Rails::Auth::ACL.from_yaml(
@@ -253,7 +259,7 @@ RSpec.describe "example_acl.yml", acl_spec: true do
   end
 
   describe "/path/to/resource" do
-    it { is_expected.to     permit get_request(principals: example_principals) }
+    it { is_expected.to     permit get_request(credentials: example_credentials) }
     it { is_expected.not_to permit get_request) }
   end
 end
@@ -261,7 +267,7 @@ end
 
 The following helper methods are available:
 
-* `x509_principal`, `x509_principal_hash`: create instance doubles of Rails::Auth::X509::Principals
+* `x509_certificate`, `x509_certificate_hash`: create instance doubles of Rails::Auth::X509::Certificate
 * Request builders: The following methods build requests from the described path:
   * `get_request`
   * `head_request`
@@ -275,7 +281,44 @@ The following helper methods are available:
 
 The following matchers are available:
 
-* `allow_request`: allows a request with the given Rack environment, and optional principals
+* `allow_request`: allows a request with the given Rack environment, and optional credentials
+
+### Error Page Middleware
+
+When an authorization error occurs, the `Rails::Auth::NotAuthorizedError`
+exception is raised up the middleware chain. However, it's likely you would
+prefer to show an error page than have an unhandled exception.
+
+You can write your own middleware that catches `Rails::Auth::NotAuthorizedError`
+if you'd like. However, a default one is provided which renders a 403 response
+with a static page body if you find that helpful.
+
+To use it, add `Rails::Auth::ErrorPage::Middleware` to your app:
+
+```ruby
+app = MyRackApp.new
+
+acl = Rails::Auth::ACL.from_yaml(
+  File.read("/path/to/my/acl.yaml")
+  matchers: { allow_x509_subject: Rails::Auth::X509::Matcher }
+)
+
+acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)
+
+x509_auth = Rails::Auth::X509::Middleware.new(
+  acl_auth,
+  ca_file: "/path/to/my/cabundle.pem"
+  cert_filters: { 'X-SSL-Client-Cert' => :pem },
+  require_cert: true
+)
+
+error_page = Rails::Auth::ErrorPage::Middleware.new(
+  x509_auth,
+  page_body: File.read("path/to/403.html")
+)
+
+run error_page
+```
 
 ## Contributing
 

data/lib/rails/auth/acl/matchers/allow_all.rb

@@ -3,7 +3,7 @@ module Rails
     class ACL
       # Built-in predicate matchers
       module Matchers
-        # Allows all principals access to a given resource
+        # Allows unauthenticated clients to access to a given resource
         class AllowAll
           def initialize(enabled)
             fail ArgumentError, "enabled must be true/false" unless [true, false].include?(enabled)

data/lib/rails/auth/credentials.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rails
+  # Modular resource-based authentication and authorization for Rails/Rack
+  module Auth
+    # Rack environment key for all rails-auth credentials
+    CREDENTIALS_ENV_KEY = "rails-auth.credentials".freeze
+
+    # Functionality for storing credentials in the Rack environment
+    module Credentials
+      # Obtain credentials from a Rack environment
+      #
+      # @param [Hash] :env Rack environment
+      #
+      def credentials(env)
+        env.fetch(CREDENTIALS_ENV_KEY, {})
+      end
+
+      # Add a credential to the Rack environment
+      #
+      # @param [Hash] :env Rack environment
+      # @param [String] :type credential type to add to the environment
+      # @param [Object] :credential object to add to the environment
+      #
+      def add_credential(env, type, credential)
+        credentials = env[CREDENTIALS_ENV_KEY] ||= {}
+
+        fail ArgumentError, "credential #{type} already added to request" if credentials.key?(type)
+        credentials[type] = credential
+      end
+    end
+
+    # Include these functions in Rails::Auth for convenience
+    extend Credentials
+  end
+end

data/lib/rails/auth/error_page/middleware.rb

@@ -0,0 +1,21 @@
+module Rails
+  module Auth
+    module ErrorPage
+      # Render an error page in the event Rails::Auth::NotAuthorizedError is raised
+      class Middleware
+        def initialize(app, page_body: nil)
+          fail TypeError, "page_body must be a String" unless page_body.is_a?(String)
+
+          @app       = app
+          @page_body = page_body.freeze
+        end
+
+        def call(env)
+          @app.call(env)
+        rescue Rails::Auth::NotAuthorizedError
+          [403, {}, [@page_body]]
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/rack.rb

@@ -5,15 +5,18 @@ require "rack"
 require "openssl"
 
 require "rails/auth/version"
+
+require "rails/auth/credentials"
 require "rails/auth/exceptions"
-require "rails/auth/principals"
 
 require "rails/auth/acl"
 require "rails/auth/acl/middleware"
 require "rails/auth/acl/resource"
 
+require "rails/auth/error_page/middleware"
+
+require "rails/auth/x509/certificate"
 require "rails/auth/x509/filter/pem"
 require "rails/auth/x509/filter/java" if defined?(JRUBY_VERSION)
 require "rails/auth/x509/matcher"
 require "rails/auth/x509/middleware"
-require "rails/auth/x509/principal"

data/lib/rails/auth/rspec/helper_methods.rb

@@ -3,14 +3,14 @@ module Rails
     module RSpec
       # RSpec helper methods
       module HelperMethods
-        # Creates an Rails::Auth::X509::Principal instance double
-        def x509_principal(cn: nil, ou: nil)
+        # Creates an Rails::Auth::X509::Certificate instance double
+        def x509_certificate(cn: nil, ou: nil)
           subject = ""
           subject << "CN=#{cn}" if cn
           subject << "OU=#{ou}" if ou
 
-          instance_double(X509::Principal, subject, cn: cn, ou: ou).tap do |principal|
-            allow(principal).to receive(:[]) do |key|
+          instance_double(Rails::Auth::X509::Certificate, subject, cn: cn, ou: ou).tap do |certificate|
+            allow(certificate).to receive(:[]) do |key|
               {
                 "CN" => cn,
                 "OU" => ou
@@ -19,13 +19,13 @@ module Rails
           end
         end
 
-        # Creates a principals hash containing a single X.509 principal instance double
-        def x509_principal_hash(**args)
-          { "x509" => x509_principal(**args) }
+        # Creates a certificates hash containing a single X.509 certificate instance double
+        def x509_certificate_hash(**args)
+          { "x509" => x509_certificate(**args) }
         end
 
         Rails::Auth::ACL::Resource::HTTP_METHODS.each do |method|
-          define_method("#{method.downcase}_request") do |principals: {}|
+          define_method("#{method.downcase}_request") do |certificates: {}|
             path = self.class.description
 
             # Warn if methods are improperly used
@@ -38,8 +38,8 @@ module Rails
               "REQUEST_PATH"   => self.class.description
             }
 
-            principals.each do |type, value|
-              Rails::Auth.add_principal(env, type.to_s, value)
+            certificates.each do |type, value|
+              Rails::Auth.add_credential(env, type.to_s, value)
             end
 
             env

data/lib/rails/auth/rspec/matchers/acl_matchers.rb

@@ -1,12 +1,12 @@
 RSpec::Matchers.define(:permit) do |env|
   description do
-    method     = env["REQUEST_METHOD"]
-    principals = Rails::Auth.principals(env)
-    message    = "allow #{method}s by "
+    method      = env["REQUEST_METHOD"]
+    credentials = Rails::Auth.credentials(env)
+    message     = "allow #{method}s by "
 
-    return message << "unauthenticated clients" if principals.count.zero?
+    return message << "unauthenticated clients" if credentials.count.zero?
 
-    message << principals.values.map(&:inspect).join(", ")
+    message << credentials.values.map(&:inspect).join(", ")
   end
 
   match { |acl| acl.match(env) }

data/lib/rails/auth/version.rb

@@ -3,6 +3,6 @@
 module Rails
   # Pluggable authentication and authorization for Rack/Rails
   module Auth
-    VERSION = "0.0.1".freeze
+    VERSION = "0.1.0".freeze
   end
 end

data/lib/rails/auth/x509/{principal.rb → certificate.rb}

@@ -3,8 +3,8 @@
 module Rails
   module Auth
     module X509
-      # HTTPS principal identified by an X.509 client certificate
-      class Principal
+      # X.509 client certificates obtained from HTTP requests
+      class Certificate
         attr_reader :certificate
 
         def initialize(certificate)

data/lib/rails/auth/x509/filter/java.rb

@@ -5,7 +5,7 @@ module Rails
   module Auth
     module X509
       module Filter
-        # Support for extracting X509::Principals from Java's sun.security.x509.X509CertImpl
+        # Extract OpenSSL::X509::Certificates from Java's sun.security.x509.X509CertImpl
         class Java
           def call(cert)
             OpenSSL::X509::Certificate.new(extract_der(cert)).freeze

data/lib/rails/auth/x509/filter/pem.rb

@@ -2,7 +2,7 @@ module Rails
   module Auth
     module X509
       module Filter
-        # Support for extracting X509::Principals from Privacy Enhanced Mail (PEM) certificates
+        # Extract OpenSSL::X509::Certificates from Privacy Enhanced Mail (PEM) certificates
         class Pem
           def call(pem)
             OpenSSL::X509::Certificate.new(pem).freeze

data/lib/rails/auth/x509/matcher.rb

@@ -1,7 +1,7 @@
 module Rails
   module Auth
     module X509
-      # Predicate matcher for making assertions about X.509 principals
+      # Predicate matcher for making assertions about X.509 certificates
       class Matcher
         # @option options [String] cn Common Name of the subject
         # @option options [String] ou Organizational Unit of the subject
@@ -11,10 +11,10 @@ module Rails
 
         # @param [Hash] env Rack environment
         def match(env)
-          principal = Rails::Auth.principals(env)["x509"]
-          return false unless principal
+          certificate = Rails::Auth.credentials(env)["x509"]
+          return false unless certificate
 
-          @options.all? { |name, value| principal[name] == value }
+          @options.all? { |name, value| certificate[name] == value }
         end
       end
     end

data/lib/rails/auth/x509/middleware.rb

@@ -6,8 +6,8 @@ module Rails
       # Raised when certificate verification is mandatory
       CertificateVerifyFailed = Class.new(NotAuthorizedError)
 
-      # Validates X.509 client certificates and adds principal objects for valid
-      # clients to the rack environment as env["rails-auth.principals"]["x509"]
+      # Validates X.509 client certificates and adds credential objects for valid
+      # clients to the rack environment as env["rails-auth.credentials"]["x509"]
       class Middleware
         # Create a new X.509 Middleware object
         #
@@ -36,15 +36,15 @@ module Rails
         end
 
         def call(env)
-          principal = extract_principal(env)
-          Rails::Auth.add_principal(env, "x509".freeze, principal.freeze) if principal
+          credential = extract_credential(env)
+          Rails::Auth.add_credential(env, "x509".freeze, credential.freeze) if credential
 
           @app.call(env)
         end
 
         private
 
-        def extract_principal(env)
+        def extract_credential(env)
           @cert_filters.each do |key, filter|
             raw_cert = env[key]
             next unless raw_cert
@@ -54,7 +54,7 @@ module Rails
 
             if @truststore.verify(cert)
               log("Verified", cert)
-              return Rails::Auth::X509::Principal.new(cert)
+              return Rails::Auth::X509::Certificate.new(cert)
             else
               log("Verify FAILED", cert)
               fail CertificateVerifyFailed, "verify failed: #{subject(cert)}" if @require_cert

data/spec/rails/auth/acl_spec.rb

@@ -6,7 +6,7 @@ RSpec.describe Rails::Auth::ACL do
       example_config,
       matchers: {
         allow_x509_subject: Rails::Auth::X509::Matcher,
-        allow_claims:       ClaimsPredicate
+        allow_claims:       ClaimsMatcher
       }
     )
   end

data/spec/rails/auth/credentials_spec.rb

@@ -0,0 +1,36 @@
+RSpec.describe Rails::Auth::Credentials do
+  describe "#credentials" do
+    let(:example_type)        { "example" }
+    let(:example_credentials) { { example_type => double(:credential) } }
+
+    let(:example_env) do
+      env_for(:get, "/").tap do |env|
+        env[Rails::Auth::CREDENTIALS_ENV_KEY] = example_credentials
+      end
+    end
+
+    it "extracts credentials from Rack environments" do
+      expect(Rails::Auth.credentials(example_env)).to eq example_credentials
+    end
+  end
+
+  describe "#add_credential" do
+    let(:example_type)       { "example" }
+    let(:example_credential) { double(:credential) }
+    let(:example_env)        { env_for(:get, "/") }
+
+    it "adds credentials to a Rack environment" do
+      expect(Rails::Auth.credentials(example_env)[example_type]).to be_nil
+      Rails::Auth.add_credential(example_env, example_type, example_credential)
+      expect(Rails::Auth.credentials(example_env)[example_type]).to eq example_credential
+    end
+
+    it "raises ArgumentError if the same type of credential is added twice" do
+      Rails::Auth.add_credential(example_env, example_type, example_credential)
+
+      expect do
+        Rails::Auth.add_credential(example_env, example_type, example_credential)
+      end.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/rails/auth/error_page/middleware_spec.rb

@@ -0,0 +1,26 @@
+RSpec.describe Rails::Auth::ErrorPage::Middleware do
+  let(:request)    { Rack::MockRequest.env_for("https://www.example.com") }
+  let(:error_page) { "<h1> Unauthorized!!! </h1>" }
+
+  subject(:middleware) { described_class.new(app, page_body: error_page) }
+
+  context "access granted" do
+    let(:code) { 200 }
+    let(:app)  { ->(env) { [code, env, "Hello, world!"] } }
+
+    it "renders the expected response" do
+      response = middleware.call(request)
+      expect(response.first).to eq code
+    end
+  end
+
+  context "access denied" do
+    let(:app) { ->(_env) { fail(Rails::Auth::NotAuthorizedError, "not authorized!") } }
+
+    it "renders the error page" do
+      code, _env, body = middleware.call(request)
+      expect(code).to eq 403
+      expect(body).to eq [error_page]
+    end
+  end
+end

data/spec/rails/auth/rspec/helper_methods_spec.rb

@@ -2,10 +2,10 @@ RSpec.describe Rails::Auth::RSpec::HelperMethods, acl_spec: true do
   let(:example_cn) { "127.0.0.1" }
   let(:example_ou) { "ponycopter" }
 
-  describe "#x509_principal" do
-    subject { x509_principal(cn: example_cn, ou: example_ou) }
+  describe "#x509_certificate" do
+    subject { x509_certificate(cn: example_cn, ou: example_ou) }
 
-    it "creates instance doubles for Rails::Auth::X509::Principals" do
+    it "creates instance doubles for Rails::Auth::X509::Certificates" do
       # Method syntax
       expect(subject.cn).to eq example_cn
       expect(subject.ou).to eq example_ou
@@ -16,10 +16,10 @@ RSpec.describe Rails::Auth::RSpec::HelperMethods, acl_spec: true do
     end
   end
 
-  describe "#x509_principal_hash" do
-    subject { x509_principal_hash(cn: example_cn, ou: example_ou) }
+  describe "#x509_certificate_hash" do
+    subject { x509_certificate_hash(cn: example_cn, ou: example_ou) }
 
-    it "creates a principal hash with an Rails::Auth::X509::Principal double" do
+    it "creates a certificate hash with an Rails::Auth::X509::Certificate double" do
       expect(subject["x509"].cn).to eq example_cn
     end
   end

data/spec/rails/auth/rspec/matchers/acl_matchers_spec.rb

@@ -1,20 +1,20 @@
 RSpec.describe "RSpec ACL matchers", acl_spec: true do
-  let(:example_principal) { x509_principal_hash(ou: "ponycopter") }
-  let(:another_principal) { x509_principal_hash(ou: "derpderp") }
+  let(:example_certificate) { x509_certificate_hash(ou: "ponycopter") }
+  let(:another_certificate) { x509_certificate_hash(ou: "derpderp") }
 
   subject do
     Rails::Auth::ACL.from_yaml(
       fixture_path("example_acl.yml").read,
       matchers: {
         allow_x509_subject: Rails::Auth::X509::Matcher,
-        allow_claims:       ClaimsPredicate
+        allow_claims:       ClaimsMatcher
       }
     )
   end
 
   describe "/baz/quux" do
-    it { is_expected.to permit get_request(principals: example_principal) }
-    it { is_expected.not_to permit get_request(principals: another_principal) }
+    it { is_expected.to permit get_request(certificates: example_certificate) }
+    it { is_expected.not_to permit get_request(certificates: another_certificate) }
     it { is_expected.not_to permit get_request }
   end
 end

data/spec/rails/auth/x509/certificate_spec.rb

@@ -0,0 +1,27 @@
+RSpec.describe Rails::Auth::X509::Certificate do
+  let(:example_cert) { OpenSSL::X509::Certificate.new(cert_path("valid.crt").read) }
+  let(:example_certificate) { described_class.new(example_cert) }
+
+  let(:example_cn) { "127.0.0.1" }
+  let(:example_ou) { "ponycopter" }
+
+  describe "#[]" do
+    it "allows access to subject components via strings" do
+      expect(example_certificate["CN"]).to eq example_cn
+      expect(example_certificate["OU"]).to eq example_ou
+    end
+
+    it "allows access to subject components via symbols" do
+      expect(example_certificate[:cn]).to eq example_cn
+      expect(example_certificate[:ou]).to eq example_ou
+    end
+  end
+
+  it "knows its #cn" do
+    expect(example_certificate.cn).to eq example_cn
+  end
+
+  it "knows its #ou" do
+    expect(example_certificate.ou).to eq example_ou
+  end
+end

data/spec/rails/auth/x509/matcher_spec.rb

@@ -1,21 +1,21 @@
 RSpec.describe Rails::Auth::X509::Matcher do
-  let(:example_cert)      { OpenSSL::X509::Certificate.new(cert_path("valid.crt").read) }
-  let(:example_principal) { Rails::Auth::X509::Principal.new(example_cert) }
+  let(:example_cert)        { OpenSSL::X509::Certificate.new(cert_path("valid.crt").read) }
+  let(:example_certificate) { Rails::Auth::X509::Certificate.new(example_cert) }
 
   let(:example_ou) { "ponycopter" }
   let(:another_ou) { "somethingelse" }
 
   let(:example_env) do
-    { Rails::Auth::PRINCIPALS_ENV_KEY => { "x509" => example_principal } }
+    { Rails::Auth::CREDENTIALS_ENV_KEY => { "x509" => example_certificate } }
   end
 
-  it "matches against a valid Rails::Auth::X509::Principal" do
-    predicate = described_class.new(ou: example_ou)
-    expect(predicate.match(example_env)).to eq true
+  it "matches against a valid Rails::Auth::X509::Credential" do
+    matcher = described_class.new(ou: example_ou)
+    expect(matcher.match(example_env)).to eq true
   end
 
   it "doesn't match if the subject mismatches" do
-    predicate = described_class.new(ou: another_ou)
-    expect(predicate.match(example_env)).to eq false
+    matcher = described_class.new(ou: another_ou)
+    expect(matcher.match(example_env)).to eq false
   end
 end

data/spec/rails/auth/x509/middleware_spec.rb

@@ -22,19 +22,20 @@ RSpec.describe Rails::Auth::X509::Middleware do
 
   context "certificate types" do
     describe "PEM certificates" do
-      it "extracts Rails::Auth::Principal::X509 from a PEM certificate in the Rack environment" do
+      it "extracts Rails::Auth::X509::Certificate from a PEM certificate in the Rack environment" do
         _response, env = middleware.call(request.merge(example_key => valid_cert_pem))
 
-        principal = Rails::Auth.principals(env).fetch("x509")
-        expect(principal).to be_a Rails::Auth::X509::Principal
+        credential = Rails::Auth.credentials(env).fetch("x509")
+        expect(credential).to be_a Rails::Auth::X509::Certificate
       end
 
       it "ignores unverified certificates" do
         _response, env = middleware.call(request.merge(example_key => bad_cert_pem))
-        expect(Rails::Auth.principals(env)).to be_empty
+        expect(Rails::Auth.credentials(env)).to be_empty
       end
     end
 
+    # :nocov:
     describe "Java certificates" do
       let(:example_key) { "javax.servlet.request.X509Certificate" }
       let(:cert_filter) { :java }
@@ -44,15 +45,16 @@ RSpec.describe Rails::Auth::X509::Middleware do
         Java::SunSecurityX509::X509CertImpl.new(ruby_cert.to_der.to_java_bytes)
       end
 
-      it "extracts Rails::Auth::Principal::X509 from a Java::SunSecurityX509::X509CertImpl" do
+      it "extracts Rails::Auth::Credential::X509 from a Java::SunSecurityX509::X509CertImpl" do
         skip "JRuby only" unless defined?(JRUBY_VERSION)
 
         _response, env = middleware.call(request.merge(example_key => java_cert))
 
-        principal = Rails::Auth.principals(env).fetch("x509")
-        expect(principal).to be_a Rails::Auth::X509::Principal
+        credential = Rails::Auth.credentials(env).fetch("x509")
+        expect(credential).to be_a Rails::Auth::X509::Certificate
       end
     end
+    # :nocov:
   end
 
   describe "require_cert: true" do
@@ -61,8 +63,8 @@ RSpec.describe Rails::Auth::X509::Middleware do
     it "functions normally for valid certificates" do
       _response, env = middleware.call(request.merge(example_key => valid_cert_pem))
 
-      principal = Rails::Auth.principals(env).fetch("x509")
-      expect(principal).to be_a Rails::Auth::X509::Principal
+      credential = Rails::Auth.credentials(env).fetch("x509")
+      expect(credential).to be_a Rails::Auth::X509::Certificate
     end
 
     it "raises Rails::Auth::X509::CertificateVerifyFailed for unverified certificates" do

data/spec/spec_helper.rb

@@ -1,8 +1,11 @@
+require "coveralls"
+Coveralls.wear!
+
 $LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
 require "rails/auth"
 require "rails/auth/rspec"
 require "support/create_certs"
-require "support/claims_predicate"
+require "support/claims_matcher"
 require "pathname"
 
 RSpec.configure(&:disable_monkey_patching!)

data/spec/support/claims_matcher.rb

@@ -0,0 +1,11 @@
+# A strawman matcher for claims-based credentials for use in tests
+class ClaimsMatcher
+  def initialize(options)
+    @options = options
+  end
+
+  def match(_env)
+    # Pretend like we have a claim to be in the "example" group
+    @options["group"] == "example"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-auth
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-26 00:00:00.000000000 Z
+date: 2016-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -65,6 +65,8 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- BUG-BOUNTY.md
+- CHANGES.md
 - CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
@@ -77,33 +79,35 @@ files:
 - lib/rails/auth/acl/matchers/allow_all.rb
 - lib/rails/auth/acl/middleware.rb
 - lib/rails/auth/acl/resource.rb
+- lib/rails/auth/credentials.rb
+- lib/rails/auth/error_page/middleware.rb
 - lib/rails/auth/exceptions.rb
-- lib/rails/auth/principals.rb
 - lib/rails/auth/rack.rb
 - lib/rails/auth/rspec.rb
 - lib/rails/auth/rspec/helper_methods.rb
 - lib/rails/auth/rspec/matchers/acl_matchers.rb
 - lib/rails/auth/version.rb
+- lib/rails/auth/x509/certificate.rb
 - lib/rails/auth/x509/filter/java.rb
 - lib/rails/auth/x509/filter/pem.rb
 - lib/rails/auth/x509/matcher.rb
 - lib/rails/auth/x509/middleware.rb
-- lib/rails/auth/x509/principal.rb
 - rails-auth.gemspec
 - spec/fixtures/example_acl.yml
 - spec/rails/auth/acl/matchers/allow_all_spec.rb
 - spec/rails/auth/acl/middleware_spec.rb
 - spec/rails/auth/acl/resource_spec.rb
 - spec/rails/auth/acl_spec.rb
-- spec/rails/auth/principals_spec.rb
+- spec/rails/auth/credentials_spec.rb
+- spec/rails/auth/error_page/middleware_spec.rb
 - spec/rails/auth/rspec/helper_methods_spec.rb
 - spec/rails/auth/rspec/matchers/acl_matchers_spec.rb
+- spec/rails/auth/x509/certificate_spec.rb
 - spec/rails/auth/x509/matcher_spec.rb
 - spec/rails/auth/x509/middleware_spec.rb
-- spec/rails/auth/x509/principal_spec.rb
 - spec/rails/auth_spec.rb
 - spec/spec_helper.rb
-- spec/support/claims_predicate.rb
+- spec/support/claims_matcher.rb
 - spec/support/create_certs.rb
 homepage: https://github.com/square/rails-auth/
 licenses:

data/lib/rails/auth/principals.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Rails
-  # Modular resource-based authentication and authorization for Rails/Rack
-  module Auth
-    # Rack environment key for all rails-auth principals
-    PRINCIPALS_ENV_KEY = "rails-auth.principals".freeze
-
-    # Functionality for storing principals in the Rack environment
-    module Principals
-      # Obtain principals from a Rack environment
-      #
-      # @param [Hash] :env Rack environment
-      #
-      def principals(env)
-        env.fetch(PRINCIPALS_ENV_KEY, {})
-      end
-
-      # Add a principal to the Rack environment
-      #
-      # @param [Hash] :env Rack environment
-      # @param [String] :type principal type to add to the environment
-      # @param [Object] :principal principal object to add to the environment
-      #
-      def add_principal(env, type, principal)
-        principals = env[PRINCIPALS_ENV_KEY] ||= {}
-
-        fail ArgumentError, "principal #{type} already added to request" if principals.key?(type)
-        principals[type] = principal
-      end
-    end
-
-    # Include these functions in Rails::Auth for convenience
-    extend Principals
-  end
-end

data/spec/rails/auth/principals_spec.rb

@@ -1,36 +0,0 @@
-RSpec.describe Rails::Auth::Principals do
-  describe "#principals" do
-    let(:example_type)       { "example" }
-    let(:example_principals) { { example_type => double(:principal) } }
-
-    let(:example_env) do
-      env_for(:get, "/").tap do |env|
-        env[Rails::Auth::PRINCIPALS_ENV_KEY] = example_principals
-      end
-    end
-
-    it "extracts principals from Rack environments" do
-      expect(Rails::Auth.principals(example_env)).to eq example_principals
-    end
-  end
-
-  describe "#add_principal" do
-    let(:example_type)      { "example" }
-    let(:example_principal) { double(:principal) }
-    let(:example_env)       { env_for(:get, "/") }
-
-    it "adds principals to a Rack environment" do
-      expect(Rails::Auth.principals(example_env)[example_type]).to be_nil
-      Rails::Auth.add_principal(example_env, example_type, example_principal)
-      expect(Rails::Auth.principals(example_env)[example_type]).to eq example_principal
-    end
-
-    it "raises ArgumentError if the same type of principal is added twice" do
-      Rails::Auth.add_principal(example_env, example_type, example_principal)
-
-      expect do
-        Rails::Auth.add_principal(example_env, example_type, example_principal)
-      end.to raise_error(ArgumentError)
-    end
-  end
-end

data/spec/rails/auth/x509/principal_spec.rb

@@ -1,27 +0,0 @@
-RSpec.describe Rails::Auth::X509::Principal do
-  let(:example_cert)      { OpenSSL::X509::Certificate.new(cert_path("valid.crt").read) }
-  let(:example_principal) { described_class.new(example_cert) }
-
-  let(:example_cn) { "127.0.0.1" }
-  let(:example_ou) { "ponycopter" }
-
-  describe "#[]" do
-    it "allows access to subject components via strings" do
-      expect(example_principal["CN"]).to eq example_cn
-      expect(example_principal["OU"]).to eq example_ou
-    end
-
-    it "allows access to subject components via symbols" do
-      expect(example_principal[:cn]).to eq example_cn
-      expect(example_principal[:ou]).to eq example_ou
-    end
-  end
-
-  it "knows its #cn" do
-    expect(example_principal.cn).to eq example_cn
-  end
-
-  it "knows its #ou" do
-    expect(example_principal.ou).to eq example_ou
-  end
-end

data/spec/support/claims_predicate.rb

@@ -1,11 +0,0 @@
-# An additional predicate class for tests
-class ClaimsPredicate
-  def initialize(options)
-    @options = options
-  end
-
-  def match(_env)
-    # Pretend like our principal is in the "example" group
-    @options["group"] == "example"
-  end
-end