graphql-guard 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2fee7151ba4f1b935f9bb185bc1ecef61920d0bc
-  data.tar.gz: d5286b90482d2e5a99827f05a3587d9f596a0669
+SHA256:
+  metadata.gz: 1356ec0ce6198540fffd1ca245c4b138792bc81ff776094a8b1ac6e12e2940d6
+  data.tar.gz: 1282de4a1c06f4c32bba870d8076fc94a276bf39cb2cb56e0cbd5f880aa73ff9
 SHA512:
-  metadata.gz: 36f519bf2ed0879655eced44f1a8062e13fcfc01d08565c7c92d33ee50cef08278e430054cc42ed9834a629dc16d3512b19cf14ef2c395a19f37929c615488c0
-  data.tar.gz: c9873f1af3b37a07398e853871f661bb45d232d79cc833aa6f0bc2aca1104e961b8e2ecf2bda3a38950de7ad91181918dbe62447cb2267ac88966b88df9c3c26
+  metadata.gz: d6c831b4be4415ed4b10f575bab5b7b2d6888965972bd9bdb7dcc1ec4477f46542e66d8b8d1566b27a3e4f044e66bc76a018920567710f4f7f723a8a6e4b02c7
+  data.tar.gz: ac3d9a36703f5f206ba40c776d2d0476a287ab99534b2e1fd27e97459ed7af3549d6cc4ef956b7f8a878f26f9b879cd8f42f0746d1c2e8d3b23f246b54f76f76

data/CHANGELOG.md

@@ -8,15 +8,19 @@ one of the following labels: `Added`, `Changed`, `Deprecated`,
 to manage the versions of this gem so
 that you can set version constraints properly.
 
-#### [Unreleased](https://github.com/exAspArk/graphql-guard/compare/v1.0.0...HEAD)
+#### [Unreleased](https://github.com/exAspArk/graphql-guard/compare/v1.1.0...HEAD)
 
 * WIP
 
+#### [v1.1.0](https://github.com/exAspArk/graphql-guard/compare/v1.0.0...v1.1.0) – 2018-05-09
+
+* `Added`: support to `mask` fields depending on the context.
+
 #### [v1.0.0](https://github.com/exAspArk/graphql-guard/compare/v0.4.0...v1.0.0) – 2017-07-31
 
 * `Changed`: guards for every `*` field also accepts arguments: `->(object, arguments, context) { ... }`:
 
-  * Before:
+Before:
 
 <pre>
 GraphQL::ObjectType.define do
@@ -26,7 +30,7 @@ GraphQL::ObjectType.define do
 end
 </pre>
 
-  * After:
+After:
 
 <pre>
 GraphQL::ObjectType.define do
@@ -38,14 +42,14 @@ end
 
 * `Changed`: `.field_with_guard` from `graphql/guard/testing` module accepts policy object as a second argument:
 
-  * Before:
+Before:
 
 <pre>
-guard_object = GraphQL::Guard.new(policy_object: GraphqlPolicy)
+<b>guard_object</b> = GraphQL::Guard.new(policy_object: GraphqlPolicy)
 posts_field = QueryType.field_with_guard('posts', <b>guard_object</b>)
 </pre>
 
-  * After:
+After:
 
 <pre>
 posts_field = QueryType.field_with_guard('posts', <b>GraphqlPolicy</b>)

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/exAspArk/graphql-guard.svg?branch=master)](https://travis-ci.org/exAspArk/graphql-guard)
 [![Coverage Status](https://coveralls.io/repos/github/exAspArk/graphql-guard/badge.svg)](https://coveralls.io/github/exAspArk/graphql-guard)
-[![Code Climate](https://img.shields.io/codeclimate/github/exAspArk/graphql-guard.svg)](https://codeclimate.com/github/exAspArk/graphql-guard)
+[![Code Climate](https://img.shields.io/codeclimate/maintainability/exAspArk/graphql-guard.svg)](https://codeclimate.com/github/exAspArk/graphql-guard/maintainability)
 [![Downloads](https://img.shields.io/gem/dt/graphql-guard.svg)](https://rubygems.org/gems/graphql-guard)
 [![Latest Version](https://img.shields.io/gem/v/graphql-guard.svg)](https://rubygems.org/gems/graphql-guard)
 
@@ -14,10 +14,11 @@ This gem provides a field-level authorization for [graphql-ruby](https://github.
   * [Inline policies](#inline-policies)
   * [Policy object](#policy-object)
 * [Priority order](#priority-order)
-* [Error handling](#error-handling)
 * [Integration](#integration)
   * [CanCanCan](#cancancan)
   * [Pundit](#pundit)
+* [Error handling](#error-handling)
+* [Schema masking](#schema-masking)
 * [Installation](#installation)
 * [Testing](#testing)
 * [Development](#development)
@@ -25,6 +26,10 @@ This gem provides a field-level authorization for [graphql-ruby](https://github.
 * [License](#license)
 * [Code of Conduct](#code-of-conduct)
 
+<a href="https://www.universe.com/" target="_blank" rel="noopener noreferrer">
+  <img src="images/universe.png" height="41" width="153" alt="Sponsored by Universe" style="max-width:100%;">
+</a>
+
 ## Usage
 
 Define a GraphQL schema:
@@ -35,14 +40,14 @@ PostType = GraphQL::ObjectType.define do
   name "Post"
 
   field :id, !types.ID
-  field :title, !types.String
+  field :title, types.String
 end
 
 # Define a query
 QueryType = GraphQL::ObjectType.define do
   name "Query"
 
-  field :posts, !types[PostType] do
+  field :posts, !types[!PostType] do
     argument :user_id, !types.ID
     resolve ->(obj, args, ctx) { Post.where(user_id: args[:user_id]) }
   end
@@ -54,7 +59,7 @@ Schema = GraphQL::Schema.define do
 end
 
 # Execute query
-GraphSchema.execute(query, variables: { user_id: 1 }, context: { current_user: current_user })
+Schema.execute(query, variables: { user_id: 1 }, context: { current_user: current_user })
 ```
 
 ### Inline policies
@@ -74,7 +79,7 @@ Now you can define `guard` for a field, which will check permissions before reso
 QueryType = GraphQL::ObjectType.define do
   name "Query"
 
-  <b>field :posts</b>, !types[PostType] do
+  <b>field :posts</b>, !types[!PostType] do
     argument :user_id, !types.ID
     <b>guard ->(obj, args, ctx) {</b> args[:user_id] == ctx[:current_user].id <b>}</b>
     ...
@@ -124,6 +129,14 @@ Schema = GraphQL::Schema.define do
 end
 </pre>
 
+When using a policy object, you may want to allow [introspection queries](http://graphql.org/learn/introspection/) to skip authorization. A simple way to avoid having to whitelist every introspection type in the `RULES` hash of your policy object is to check the `type` parameter in the `guard` method:
+
+<pre>
+def self.guard(type, field)
+  <b>type.introspection? ? ->(_obj, _args, _ctx) { true } :</b> RULES.dig(type, field) # or "false" to restrict an access
+end
+</pre>
+
 ## Priority order
 
 `GraphQL::Guard` will use the policy in the following order of priority:
@@ -159,34 +172,6 @@ Schema = GraphQL::Schema.define do
 end
 </pre>
 
-## Error handling
-
-By default `GraphQL::Guard` raises a `GraphQL::Guard::NotAuthorizedError` exception if access to field is not authorized.
-You can change this behavior, by passing custom `not_authorized` lambda. For example:
-
-<pre>
-SchemaWithErrors = GraphQL::Schema.define do
-  query QueryType
-  use GraphQL::Guard.new(
-    # Returns an error in the response
-    <b>not_authorized: ->(type, field) { GraphQL::ExecutionError.new("Not authorized to access #{type}.#{field}") }</b>
-
-    # By default it raises an error
-    # not_authorized: ->(type, field) { raise GraphQL::Guard::NotAuthorizedError.new("#{type}.#{field}") }
-  )
-end
-</pre>
-
-In this case executing a query will continue, but return `nil` for not authorized field and also an array of `errors`:
-
-<pre>
-SchemaWithErrors.execute("query { <b>posts</b>(user_id: 1) { id title } }")
-# => {
-#   "data" => <b>nil</b>,
-#   "errors" => [{ "messages" => <b>"Not authorized to access Query.posts"</b>, "locations": { ... }, "path" => [<b>"posts"</b>] }]
-# }
-</pre>
-
 ## Integration
 
 You can simply reuse your existing policies if you really want. You don't need any monkey patches or magic for it ;)
@@ -211,12 +196,12 @@ end
 # Use the ability in your guard
 PostType = GraphQL::ObjectType.define do
   name "Post"
-  <b>guard ->(post, args, ctx) { ctx[:current_ability].can?(:read, post) }</b>
+  guard ->(post, args, ctx) { <b>ctx[:current_ability].can?(:read, post)</b> }
   ...
 end
 
 # Pass the ability
-GraphSchema.execute(query, context: { <b>current_ability: Ability.new(current_user)</b> })
+Schema.execute(query, context: { <b>current_ability: Ability.new(current_user)</b> })
 </pre>
 
 ### Pundit
@@ -232,12 +217,100 @@ end
 # Use the ability in your guard
 PostType = GraphQL::ObjectType.define do
   name "Post"
-  <b>guard ->(post, args, ctx) { PostPolicy.new(ctx[:current_user], post).show? }</b>
+  guard ->(post, args, ctx) { <b>PostPolicy.new(ctx[:current_user], post).show?</b> }
   ...
 end
 
 # Pass current_user
-GraphSchema.execute(query, context: { <b>current_user: current_user</b> })
+Schema.execute(query, context: { <b>current_user: current_user</b> })
+</pre>
+
+## Error handling
+
+By default `GraphQL::Guard` raises a `GraphQL::Guard::NotAuthorizedError` exception if access to the field is not authorized.
+You can change this behavior, by passing custom `not_authorized` lambda. For example:
+
+<pre>
+SchemaWithErrors = GraphQL::Schema.define do
+  query QueryType
+  use GraphQL::Guard.new(
+    # By default it raises an error
+    # not_authorized: ->(type, field) { raise GraphQL::Guard::NotAuthorizedError.new("#{type}.#{field}") }
+
+    # Returns an error in the response
+    <b>not_authorized: ->(type, field) { GraphQL::ExecutionError.new("Not authorized to access #{type}.#{field}") }</b>
+  )
+end
+</pre>
+
+In this case executing a query will continue, but return `nil` for not authorized field and also an array of `errors`:
+
+<pre>
+SchemaWithErrors.execute("query { <b>posts</b>(user_id: 1) { id title } }")
+# => {
+#   "data" => <b>nil</b>,
+#   "errors" => [{
+#     "messages" => <b>"Not authorized to access Query.posts"</b>,
+#     "locations": { "line" => 1, "column" => 9 },
+#     "path" => [<b>"posts"</b>]
+#   }]
+# }
+</pre>
+
+In more advanced cases, you may want not to return `errors` only for some unauthorized fields. Simply return `nil` if user is not authorized to access the field. You can achieve it, for example, by placing the logic into your `PolicyObject`:
+
+<pre>
+class <b>GraphqlPolicy</b>
+  RULES = {
+    PostType => {
+      '*': {
+        guard: ->(obj, args, ctx) { ... },
+        <b>not_authorized:</b> ->(type, field) { GraphQL::ExecutionError.new("Not authorized to access #{type}.#{field}") }
+      }
+      title: {
+        guard: ->(obj, args, ctx) { ... },
+        <b>not_authorized:</b> ->(type, field) { nil } # simply return nil if not authorized, no errors
+      }
+    }
+  }
+
+  def self.guard(type, field)
+    RULES.dig(type, field, :guard)
+  end
+
+  def self.<b>not_authorized_handler</b>(type, field)
+    RULES</b>.dig(type, field, <b>:not_authorized</b>) || RULES</b>.dig(type, :'*', <b>:not_authorized</b>)
+  end
+end
+
+Schema = GraphQL::Schema.define do
+  query QueryType
+  mutation MutationType
+
+  use GraphQL::Guard.new(
+    policy_object: GraphqlPolicy,
+    not_authorized: ->(type, field) {
+      handler = GraphqlPolicy.<b>not_authorized_handler</b>(type, field)
+      handler.call(type, field)
+    }
+  )
+end
+</pre>
+
+## Schema masking
+
+It's possible to hide fields from being introspectable and accessible based on the context. For example:
+
+<pre>
+PostType = GraphQL::ObjectType.define do
+  name "Post"
+
+  field :id, !types.ID
+  field :title, types.String do
+    # The field "title" is accessible only for beta testers
+    <b>mask ->(ctx) {</b> ctx[:current_user].beta_tester? <b>}</b>
+  end
+end
 </pre>
 
 ## Installation
@@ -264,7 +337,7 @@ It's possible to test fields with `guard` in isolation:
 # Your type
 QueryType = GraphQL::ObjectType.define do
   name "Query"
-  <b>field :posts</b>, !types[PostType], <b>guard ->(obj, args, ctx) {</b> ... <b>}</b>
+  <b>field :posts</b>, !types[!PostType], <b>guard ->(obj, args, ctx) {</b> ... <b>}</b>
 end
 
 # Your test
@@ -282,7 +355,7 @@ If you would like to test your fields with policy objects:
 # Your type
 QueryType = GraphQL::ObjectType.define do
   name "Query"
-  <b>field :posts</b>, !types[PostType]
+  <b>field :posts</b>, !types[!PostType]
 end
 
 # Your policy object

data/graphql-guard.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+    f.match(%r{^(spec|images)/})
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

data/lib/graphql/guard.rb

@@ -5,6 +5,7 @@ require "graphql/guard/version"
 
 GraphQL::ObjectType.accepts_definitions(guard: GraphQL::Define.assign_metadata_key(:guard))
 GraphQL::Field.accepts_definitions(guard: GraphQL::Define.assign_metadata_key(:guard))
+GraphQL::Field.accepts_definitions(mask: GraphQL::Define.assign_metadata_key(:mask))
 
 module GraphQL
   class Guard
@@ -22,6 +23,13 @@ module GraphQL
 
     def use(schema_definition)
       schema_definition.instrument(:field, self)
+      schema_definition.target.instance_eval do
+        def default_filter
+          GraphQL::Filter.new(except: default_mask).merge(only: ->(schema_member, ctx) {
+            schema_member.metadata[:mask] ? schema_member.metadata[:mask].call(ctx) : true
+          })
+        end
+      end
     end
 
     def instrument(type, field)

data/lib/graphql/guard/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   class Guard
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-guard
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - exAspArk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-31 00:00:00.000000000 Z
+date: 2018-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -115,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Simple authorization gem for graphql-ruby