feat: scopes

Author: adamcooke

doc/scopes.md

@@ -0,0 +1,53 @@
+# Scopes
+
+Scopes are used to restrict access to endpoints. You can, optionally, assign scopes to endpoints and the authenticator will be responsible to ensuring are satisified for the authenticating entity before allowing the request to proceed.
+
+## Configuring endpoints
+
+You should add a list of supported scopes to each endpoint. If an endpoint doesn't specify any scopes it will always be permitted. If you specify multiple scopes, possession of any of scopes will allow the endpoint to be executed.
+
+```ruby
+endpoint :list do
+  name 'List all widgets'
+  scopes 'widgets', 'widgets:read'
+  # ... rest of the method
+end
+```
+
+## Configuring the authenticator
+
+The authenticator is responsible for determining whether or not an authenticated identity possesses a scope. You do this by defining a `scope_validator` which contains the logic required to determine whether the given scope is available or not.
+
+```ruby
+module CoreAPI
+  class Authenticator < Rapid::Authenticator
+
+    # ...
+
+    scope_validator do |scope|
+      request.identity.has_scope?(scope)
+    end
+
+  end
+end
+```
+
+## Providing scope details
+
+The schema will contain a list of all scopes that are available within the API. You can decorate this by providing a description for each scope as necessary.
+
+```ruby
+module CoreAPI
+  class Base < Rapid::API
+
+    # ...
+
+    scopes do
+      add "widgets", "Full access to all widgets"
+      add "widgets:read", "Read-only access to all widgets"
+      add "self", "Access to user details"
+    end
+
+  end
+end
+```

examples/core_api/base.rb

@@ -8,6 +8,10 @@ class Base < Rapid::API
 
     authenticator MainAuthenticator
 
+    scopes do
+      add 'time', 'Allows time telling functions'
+    end
+
     routes do
       schema
 

examples/core_api/controllers/time_controller.rb

@@ -13,6 +13,7 @@ class TimeController < Rapid::Controller
       endpoint :now do
         description 'Returns the current time'
         field :time, type: Objects::Time, include: 'unix,day_of_week'
+        scope 'time'
         action do |_request, response|
           time = Time.now
           response.add_field :time, time

lib/rapid/authenticator.rb

@@ -39,6 +39,17 @@ def execute(environment)
         environment.call(&definition.action)
       end
 
+      # If any of the given scopes are valid
+      #
+      # @param scope [String]
+      # @return [Boolean]
+      def authorized_scope?(scopes)
+        return true if definition.scope_validator.nil?
+        return true if scopes.empty?
+
+        scopes.any? { |s| definition.scope_validator.call(s) }
+      end
+
     end
 
   end

lib/rapid/definitions/api.rb

@@ -13,11 +13,13 @@ class API < Definition
       attr_reader :controllers
       attr_reader :route_set
       attr_reader :exception_handlers
+      attr_reader :scopes
 
       def setup
         @route_set = RouteSet.new
         @controllers = {}
         @exception_handlers = HookSet.new
+        @scopes = {}
       end
 
       def dsl

lib/rapid/definitions/authenticator.rb

@@ -11,6 +11,7 @@ class Authenticator < Definition
 
       attr_accessor :type
       attr_accessor :action
+      attr_accessor :scope_validator
       attr_reader :potential_errors
 
       def setup

lib/rapid/definitions/endpoint.rb

@@ -16,10 +16,12 @@ class Endpoint < Definition
       attr_accessor :http_status
       attr_accessor :paginated_field
       attr_reader :fields
+      attr_reader :scopes
 
       def setup
         @fields = FieldSet.new
         @http_status = 200
+        @scopes = []
       end
 
       def argument_set

lib/rapid/dsls/api.rb

@@ -2,6 +2,7 @@
 
 require 'rapid/dsl'
 require 'rapid/helpers'
+require 'rapid/dsls/scope_descriptions'
 
 module Rapid
   module DSLs
@@ -24,6 +25,13 @@ def routes(&block)
         @definition.route_set.dsl.instance_eval(&block) if block_given?
       end
 
+      def scopes(&block)
+        return unless block_given?
+
+        dsl = DSLs::ScopeDescriptions.new(@definition)
+        dsl.instance_eval(&block)
+      end
+
     end
   end
 end

lib/rapid/dsls/authenticator.rb

@@ -2,6 +2,7 @@
 
 require 'rapid/dsl'
 require 'rapid/helpers'
+require 'rapid/errors/scope_not_granted_error'
 
 module Rapid
   module DSLs
@@ -24,6 +25,14 @@ def action(&block)
         @definition.action = block
       end
 
+      def scope_validator(&block)
+        unless @definition.potential_errors.include?(Rapid::ScopeNotGrantedError)
+          potential_error Rapid::ScopeNotGrantedError
+        end
+
+        @definition.scope_validator = block
+      end
+
     end
   end
 end

lib/rapid/dsls/endpoint.rb

@@ -64,6 +64,16 @@ def field(name, *args, type: nil, **options, &block)
         super(name, *args, type: type, **options, &block)
       end
 
+      def scopes(*names)
+        names.each { |name| scope(name) }
+      end
+
+      def scope(name)
+        return if @definition.scopes.include?(name.to_s)
+
+        @definition.scopes << name.to_s
+      end
+
     end
   end
 end

lib/rapid/dsls/scope_descriptions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Rapid
+  module DSLs
+    class ScopeDescriptions
+
+      def initialize(api)
+        @api = api
+      end
+
+      def add(name, description)
+        @api.scopes[name.to_s] = { description: description }
+      end
+
+    end
+  end
+end

lib/rapid/endpoint.rb

@@ -4,6 +4,7 @@
 require 'rapid/defineable'
 require 'rapid/definitions/endpoint'
 require 'rapid/request_environment'
+require 'rapid/errors/scope_not_granted_error'
 
 module Rapid
   class Endpoint
@@ -49,6 +50,11 @@ def execute(request)
           request.authenticator = definition.authenticator || request.controller&.definition&.authenticator || request.api&.definition&.authenticator
           request.authenticator&.execute(environment)
 
+          # Determine if we're permitted to run the action based on the endpoint's scopes
+          if request.authenticator && !request.authenticator.authorized_scope?(definition.scopes)
+            environment.raise_error Rapid::ScopeNotGrantedError, scopes: definition.scopes
+          end
+
           # Process arguments into the request. This happens after the authentication
           # stage because a) authenticators shouldn't be using endpoint specific args
           # and b) the argument conditions may need to know the identity.

lib/rapid/errors/scope_not_granted_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rapid/error'
+
+module Rapid
+  class ScopeNotGrantedError < Rapid::Error
+
+    code :scope_not_granted
+    http_status 403
+    description 'The scope required for this endpoint has not been granted to the authenticating identity'
+
+    field :scopes, [:string]
+
+  end
+end

lib/rapid/schema/api_schema_type.rb

@@ -5,6 +5,7 @@
 require 'rapid/schema/api_controller_schema_type'
 require 'rapid/schema/object_schema_polymorph'
 require 'rapid/schema/route_set_schema_type'
+require 'rapid/schema/scope_type'
 
 module Rapid
   module Schema
@@ -31,6 +32,11 @@ class APISchemaType < Rapid::Object
       end
 
       field :route_set, type: RouteSetSchemaType
+      field :scopes, type: [ScopeType] do
+        backend do |api|
+          api.scopes.map { |k, v| v.merge(name: k) }
+        end
+      end
 
     end
   end

lib/rapid/schema/endpoint_schema_type.rb

@@ -28,6 +28,7 @@ class EndpointSchemaType < Rapid::Object
       field :potential_errors, type: [:string] do
         backend { |a| a.potential_errors.map { |e| e.definition.id } }
       end
+      field :scopes, type: [:string]
 
     end
   end

lib/rapid/schema/scope_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rapid/object'
+
+module Rapid
+  module Schema
+    class ScopeType < Rapid::Object
+
+      field :name, :string
+      field :description, :string
+
+    end
+  end
+end

spec/specs/rapid/authenticator_spec.rb

@@ -41,4 +41,32 @@
       expect(response.headers['x-executed']).to eq '123'
     end
   end
+
+  context '.authorized_scope?' do
+    it 'returns true if any of the scopes are valid' do
+      auth = Rapid::Authenticator.create('ExampleAuthenticator') do
+        scope_validator { |s| s == 'example' }
+      end
+      expect(auth.authorized_scope?(%w[example another])).to be true
+    end
+
+    it 'returns true if no scopes are provided' do
+      auth = Rapid::Authenticator.create('ExampleAuthenticator') do
+        scope_validator { |s| s == 'example' }
+      end
+      expect(auth.authorized_scope?([])).to be true
+    end
+
+    it 'returns true if there is no scope validator for the authenticator' do
+      auth = Rapid::Authenticator.create('ExampleAuthenticator')
+      expect(auth.authorized_scope?(['example'])).to be true
+    end
+
+    it 'returns false if none of the scopes are valid' do
+      auth = Rapid::Authenticator.create('ExampleAuthenticator') do
+        scope_validator { |s| s == 'example' }
+      end
+      expect(auth.authorized_scope?(['another'])).to be false
+    end
+  end
 end

spec/specs/rapid/dsls/api_spec.rb

@@ -68,4 +68,14 @@
       expect(api.route_set.find(:get, 'virtual_machines').first).to be_a Rapid::Route
     end
   end
+
+  context '#scopes' do
+    it 'allows for scopes to be defined' do
+      dsl.scopes do
+        add 'widgets', 'Full access to widgets'
+        add 'widgets:read', 'Read-only access to widgets'
+      end
+      expect(api.scopes).to eq({ 'widgets' => { description: 'Full access to widgets' }, 'widgets:read' => { description: 'Read-only access to widgets' } })
+    end
+  end
 end

spec/specs/rapid/dsls/authenticator_spec.rb

@@ -54,4 +54,16 @@
       expect(authenticator.action.call).to eq 10
     end
   end
+
+  context '#scope_validator' do
+    it 'allows a block to be defined' do
+      dsl.scope_validator { 1234 }
+      expect(authenticator.scope_validator.call).to eq 1234
+    end
+
+    it 'adds the scope not granted potential error' do
+      dsl.scope_validator { 1234 }
+      expect(authenticator.potential_errors).to include Rapid::ScopeNotGrantedError
+    end
+  end
 end

spec/specs/rapid/dsls/endpoint_spec.rb

@@ -124,4 +124,24 @@
       end
     end
   end
+
+  context '#scope' do
+    it 'should add a scope' do
+      dsl.scope 'example:read'
+      expect(endpoint.scopes).to eq ['example:read']
+    end
+
+    it 'should not add the same scope twice' do
+      dsl.scope 'example:read'
+      dsl.scope 'example:read'
+      expect(endpoint.scopes).to eq ['example:read']
+    end
+  end
+
+  context '#scopes' do
+    it 'should add multiple scopes' do
+      dsl.scopes 'example:read', 'example:write'
+      expect(endpoint.scopes).to eq ['example:read', 'example:write']
+    end
+  end
 end