action_policy-graphql 0.0.1 → 0.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67e8da87c493d0478d778ba4421a404af3fd7b9f84cb95529f9f72a31c7221fb
-  data.tar.gz: 19f45c885b52f2615d93872d67603e0b9ff07ae5ddb0a61805eeaa6fe4d4e024
+  metadata.gz: 3c8a905655156e38c918dc3b222dff1d8642d61416892b3ce89bf033adc08dcf
+  data.tar.gz: 4d9994c62eb097299b2e7199dd656cb64d859983b6da0778929ba86bc21f58b8
 SHA512:
-  metadata.gz: dc240bd69108871bf60f7ef9b95fbd88565e14a3fdb21542e4330a8a5dbcbaf625ce9fe00cd0fb4caa24dd76e820c27a3975a5eb4862fbb95e130dcd0d1ff873
-  data.tar.gz: e99ed4c366a6ae8877e0d37eb8bffbec71e6f2d6e0f0acc1bff93250b02b6146f77c89a453e409b2ecd7b2ea37418cf1966793d9f177f250392dacb2740ddd15
+  metadata.gz: bc7c087373d6ddf13d6f659a923ee786589d79861fb11f772104e4e5ae3a262d6160a55062340fda17c3729f3ece2461fdd25cc2f55412c2119e73374241cad1
+  data.tar.gz: 1ee3ad7f30ad9a37ed728fe8bde93d2405d0e57cc26aae78a204930e22abedd40d3b3381a061da7904eeb21f6af4023423627fa8533e7776d80b646fe5d77af6

data/README.md

@@ -6,6 +6,11 @@
 
 This gem provides an integration for using [Action Policy](https://github.com/palkan/action_policy) as an authorization framework for GraphQL applications (built with [`graphql` ruby gem](https://graphql-ruby.org)).
 
+This integration includes the following features:
+- Fields & mutations authorization
+- List and connections scoping
+- **Exposing permissions/authorization rules in the API**.
+
 📑 [Documentation](https://actionpolicy.evilmartians.io/#/graphql)
 
 <a href="https://evilmartians.com/?utm_source=action_policy-graphql">
@@ -25,7 +30,106 @@ And then execute:
 
 ## Usage
 
-TBD
+**NOTE:** this is a quick overview of the functionality provided by the gem. For more information see the [documentation](https://actionpolicy.evilmartians.io/#/graphql).
+
+To start using Action Policy in GraphQL-related code, you need to enhance your base classes with `ActionPolicy::GraphQL::Behaviour`:
+
+```ruby
+# For fields authorization, lists scoping and rules exposing
+class Types::BaseObject < GraphQL::Schema::Object
+  include ActionPolicy::GraphQL::Behaviour
+end
+
+# For using authorization helpers in mutations
+class Types::BaseMutation < GraphQL::Schema::Mutation
+  include ActionPolicy::GraphQL::Behaviour
+end
+```
+
+### `authorize: *`
+
+You can add authorization to the fields by specifying the `authorize: *` option:
+
+```
+field :home, Home, null: false, authorize: true do
+  argument :id, ID, required: true
+end
+
+# field resolver method
+def home(id:)
+  Home.find(id)
+end
+```
+
+The code above is equal to:
+
+```ruby
+field :home, Home, null: false do
+  argument :id, ID, required: true
+end
+
+def home(id:)
+  Home.find(id).tap { |home| authorize! home, to: :show? }
+end
+```
+
+You can customize the authorization options, e.g. `authorize: {to: :preview?, with: CustomPolicy}`.
+
+### `authorized_scope`
+
+You can add `authorized_scope: true` option to the field (list or _connection_ field) to
+apply the corresponding policy rules to the data:
+
+```ruby
+class CityType < ::Common::Graphql::Type
+  # It would automatically apply the relation scope from the EventPolicy to
+  # the relation (city.events)
+  field :events, EventType.connection_type, null: false, authorized_scope: true
+
+  # you can specify the policy explicitly
+  field :events, EventType.connection_type, null: false, authorized_scope: {with: CustomEventPolicy}
+end
+```
+
+### `expose_authorization_rules`
+
+You can add permissions/authorization exposing fields to "tell" clients which actions could be performed against the object or not (and why).
+
+For example:
+
+```ruby
+class ProfileType < ::Common::Graphql::Type
+  # Adds can_edit, can_destroy fields with
+  # AuthorizationResult type.
+
+  # NOTE: prefix "can_" is used by default, no need to specify it explicitly
+  expose_authorization_rules :edit?, :destroy?, prefix: "can_"
+end
+```
+
+Then the client could perform the following query:
+
+```gql
+{
+  post(id: $id) {
+    canEdit {
+      # (bool) true|false; not null
+      value
+      # top-level decline message ("Not authorized" by default); null if value is true
+      message
+      # detailed information about the decline reasons; null if value is true
+      reasons {
+        details # JSON-encoded hash of the form { "community/event" => [:privacy_off?] }
+        fullMessages # Array of human-readable reasons
+      }
+    }
+
+    canDestroy {
+      # ...
+    }
+  }
+}
+```
 
 ## Contributing
 

data/lib/action_policy/graphql/authorized_field.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module GraphQL
+    # Add `authorized` option to the field
+    #
+    # Example:
+    #
+    #   class PostType < ::GraphQL::Schema::Object
+    #     field :comments, null: false, authorized: true
+    #
+    #     # or with options
+    #     field :comments, null: false, authorized: { type: :relation, with: MyPostPolicy }
+    #   end
+    module AuthorizedField
+      class AuthorizeExtension < ::GraphQL::Schema::FieldExtension
+        def initialize(*)
+          super
+          options[:to] ||= ::ActionPolicy::GraphQL.default_authorize_rule
+          options[:raise] = ::ActionPolicy::GraphQL.authorize_raise_exception unless options.key?(:raise)
+        end
+
+        def after_resolve(value:, context:, object:, **_rest)
+          return value if value.nil?
+
+          if options[:raise]
+            object.authorize! value, **options
+            value
+          else
+            object.allowed_to?(options[:to], value, options) ? value : nil
+          end
+        end
+      end
+
+      class ScopeExtension < ::GraphQL::Schema::FieldExtension
+        def after_resolve(value:, context:, object:, **_rest)
+          return value if value.nil?
+
+          object.authorized_scope(value, **options)
+        end
+      end
+
+      def initialize(*args, authorize: nil, authorized_scope: nil, **kwargs, &block)
+        if authorize && authorized_scope
+          raise ArgumentError, "Only one of `authorize` and `authorized_scope` " \
+                               "options could be specified"
+        end
+
+        options = authorize || authorized_scope
+
+        if options
+          options = {} if options == true
+
+          extension_class = authorized_scope ? ScopeExtension : AuthorizeExtension
+
+          extension = {extension_class => options}
+
+          extensions = (kwargs[:extensions] ||= [])
+
+          if extensions.is_a?(Hash)
+            extensions.merge!(extension)
+          else
+            extensions << extension
+          end
+        end
+
+        super(*args, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/action_policy/graphql/behaviour.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "action_policy/graphql/fields"
+require "action_policy/graphql/authorized_field"
+
+module ActionPolicy
+  module GraphQL
+    module Behaviour
+      def self.included(base)
+        base.include ActionPolicy::Behaviour
+        base.include ActionPolicy::Behaviours::ThreadMemoized
+        base.include ActionPolicy::Behaviours::Memoized
+        base.include ActionPolicy::Behaviours::Namespaced
+
+        base.field_class.prepend(ActionPolicy::GraphQL::AuthorizedField)
+        base.authorize :user, through: :current_user
+
+        base.include ActionPolicy::GraphQL::Fields
+      end
+
+      def current_user
+        context[:current_user]
+      end
+    end
+  end
+end

data/lib/action_policy/graphql/fields.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "action_policy/graphql/types/authorization_result"
+
+module ActionPolicy
+  module GraphQL
+    # Add DSL to add policy rules as fields
+    #
+    # Example:
+    #
+    #   class PostType < ::GraphQL::Schema::Object
+    #     # Adds can_edit, can_destroy fields with
+    #     # AuthorizationResult type.
+    #
+    #     expose_authorization_rules :edit?, :destroy?, prefix: "can_"
+    #   end
+    #
+    # Prefix is "can_" by default.
+    module Fields
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      def allowance_to(rule, target = object, **options)
+        policy_for(record: target, **options).yield_self do |policy|
+          policy.apply(authorization_rule_for(policy, rule))
+          policy.result
+        end
+      end
+
+      module ClassMethods
+        def expose_authorization_rules(*rules, prefix: ::ActionPolicy::GraphQL.default_authorization_field_prefix, **options)
+          rules.each do |rule|
+            field_name = "#{prefix}#{rule.to_s.delete("?")}"
+
+            field field_name,
+                  ActionPolicy::GraphQL::Types::AuthorizationResult,
+                  null: false
+
+            define_method(field_name) do
+              allowance_to(rule, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/graphql/types/authorization_result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "action_policy/graphql/types/failure_reasons"
+
+module ActionPolicy
+  module GraphQL
+    module Types
+      class AuthorizationResult < ::GraphQL::Schema::Object
+        field :value, Boolean, null: false, description: "Result of applying a policy rule"
+        field :message, String, null: true, description: "Human-readable error message"
+        field :reasons, FailureReasons, null: true, description: "Reasons of check failure"
+
+        def message
+          return if object.value == true
+          object.message
+        end
+
+        def reasons
+          return if object.value == true
+          object.reasons
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/graphql/types/failure_reasons.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module GraphQL
+    module Types
+      class FailureReasons < ::GraphQL::Schema::Object
+        field :details, String, null: false, description: "JSON-encoded map of reasons"
+        field :full_messages, [String], null: false, description: "Human-readable errors"
+
+        def details
+          object.details.to_json
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module ActionPolicy
   module GraphQL
-    VERSION = "0.0.1"
+    VERSION = "0.1.0.rc1"
   end
 end

data/lib/action_policy/graphql.rb

@@ -1,11 +1,29 @@
 # frozen_string_literal: true
 
-require "action_policy"
 require "graphql"
+require "action_policy"
 
-require "action_policy/graphql/version"
+require "action_policy/graphql/behaviour"
 
 module ActionPolicy
   module GraphQL
+    class << self
+      # Which rule to use when no specified (e.g. `authorize: true`)
+      # Defaults to `:show?`
+      attr_accessor :default_authorize_rule
+
+      # Whether to raise an exeption if field is not authorized
+      # or return `nil`.
+      # Defaults to `true`.
+      attr_accessor :authorize_raise_exception
+
+      # Which prefix to use for authorization fields
+      # Defaults to `"can_"`
+      attr_accessor :default_authorization_field_prefix
+    end
+
+    self.default_authorize_rule = :show?
+    self.authorize_raise_exception = true
+    self.default_authorization_field_prefix = "can_"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: action_policy-graphql
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0.rc1
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-20 00:00:00.000000000 Z
+date: 2019-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: action_policy
@@ -144,7 +144,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
@@ -159,6 +158,11 @@ files:
 - gemfiles/jruby.gemfile
 - lib/action_policy-graphql.rb
 - lib/action_policy/graphql.rb
+- lib/action_policy/graphql/authorized_field.rb
+- lib/action_policy/graphql/behaviour.rb
+- lib/action_policy/graphql/fields.rb
+- lib/action_policy/graphql/types/authorization_result.rb
+- lib/action_policy/graphql/types/failure_reasons.rb
 - lib/action_policy/graphql/version.rb
 homepage: https://github.com/palkan/action_policy-graphql
 licenses:
@@ -180,9 +184,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.3
 signing_key: 

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper