warrant 1.1.0 → 2.0.0.rc1

data/lib/warrant/models/warrant.rb

@@ -2,25 +2,24 @@
 
 module Warrant
     class Warrant
-        attr_reader :id, :object_type, :object_id, :relation, :subject
+        attr_reader :id, :object_type, :object_id, :relation, :subject, :context, :is_direct_match
 
         # @!visibility private
-        def initialize(object_type, object_id, relation, subject)
+        def initialize(object_type, object_id, relation, subject, context = nil, is_direct_match = nil)
             @object_type = object_type
             @object_id = object_id
             @relation = relation
             @subject = subject
+            @context = context
+            @is_direct_match = is_direct_match
         end
 
         # Create a new warrant that associates an object (object_type and object_id) to a subject via a relation.
         #
-        # @option params [String] :object_type The type of object. Must be one of your system's existing object types.
-        # @option params [String] :object_id The id of the specific object.
-        # @option params [String] :relation The relation for this object to subject association. The relation must be valid as per the object type definition.
-        # @option params [Hash] :subject The specific subject (object, user etc.) to be associated with the object. A subject can either be a specific object (by id) or a group of objects defined by a set containing an objectType, objectId and relation.
-        #   * :object_type (String) - The type of object. Must be one of your system's existing object types.
-        #   * :object_id (String) - The id of the specific object.
-        #   * :relation (String) - The relation for this object to subject association. The relation must be valid as per the object type definition. (optional)
+        # @param object [WarrantObject] Object to check in the access check. Object must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`). The object type must be one of your system's existing object type.
+        # @param relation [String] The relation to check for this object to subject association. The relation must be valid as per the object type definition.
+        # @param subject [WarrantObject] Subject to check in the access check. Subject must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`).
+        # @param context [Hash] - Object containing key-value pairs that specifies the context the warrant should be created for. (optional)
         #
         # @return [Warrant] created warrant
         #
@@ -28,18 +27,27 @@ module Warrant
         # @raise [Warrant::InternalError]
         # @raise [Warrant::InvalidParameterError]
         # @raise [Warrant::InvalidRequestError]
-        # @raise [Warrant::MissingRequiredParameterError]
         # @raise [Warrant::NotFoundError]
         # @raise [Warrant::UnauthorizedError]
         # @raise [Warrant::WarrantError]
-        def self.create(params = {})
+        def self.create(object, relation, subject, context = nil)
+            params = {
+                object_type: object.warrant_object_type,
+                object_id: object.warrant_object_id,
+                relation: relation,
+                subject: {
+                    object_type: subject.warrant_object_type,
+                    object_id: subject.warrant_object_id
+                },
+                context: context
+            }
             res = APIOperations.post(URI.parse("#{::Warrant.config.api_base}/v1/warrants"), Util.normalize_params(params))
             res_json = JSON.parse(res.body)
 
             case res
             when Net::HTTPSuccess
-                subject = Subject.new(res_json['subject']['objectType'], res_json['subject']['objectId'])
-                Warrant.new(res_json['objectType'], res_json['objectId'], res_json['relation'], subject)
+                subject = Subject.new(res_json['subject']['objectType'], res_json['subject']['objectId'], res_json['subject']['relation'])
+                Warrant.new(res_json['objectType'], res_json['objectId'], res_json['relation'], subject, res_json['context'])
             else
                 APIOperations.raise_error(res)
             end
@@ -47,24 +55,29 @@ module Warrant
 
         # Deletes a warrant specified by the combination of object_type, object_id, relation, and subject.
         #
-        # @option params [String] :object_type The type of object. Must be one of your system's existing object types.
-        # @option params [String] :object_id The id of the specific object.
-        # @option params [String] :relation The relation for this object to subject association. The relation must be valid as per the object type definition.
-        # @option params [Hash] :subject The specific subject (object, user etc.) to be associated with the object. A subject can either be a specific object (by id) or a group of objects defined by a set containing an objectType, objectId and relation.
-        #   * :object_type [String] The type of object. Must be one of your system's existing object types.
-        #   * :object_id [String] The id of the specific object.
-        #   * :relation [String] The relation for this object to subject association. The relation must be valid as per the object type definition. (optional)
+        # @param object [WarrantObject] Object to check in the access check. Object must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`). The object type must be one of your system's existing object type.
+        # @param relation [String] The relation to check for this object to subject association. The relation must be valid as per the object type definition.
+        # @param subject [WarrantObject] Subject to check in the access check. Subject must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`).
+        # @param context [Hash] - Object containing key-value pairs that specifies the context the warrant should be deleted in. (optional)
         #
         # @return [nil] if delete was successful
         #
         # @raise [Warrant::InternalError]
-        # @raise [Warrant::InvalidParameterError]
         # @raise [Warrant::InvalidRequestError]
-        # @raise [Warrant::MissingRequiredParameterError]
         # @raise [Warrant::NotFoundError]
         # @raise [Warrant::UnauthorizedError]
         # @raise [Warrant::WarrantError]
-        def self.delete(params = {})
+        def self.delete(object, relation, subject, context = nil)
+            params = {
+                object_type: object.warrant_object_type,
+                object_id: object.warrant_object_id,
+                relation: relation,
+                subject: {
+                    object_type: subject.warrant_object_type,
+                    object_id: subject.warrant_object_id
+                },
+                context: context
+            }
             res = APIOperations.delete(URI.parse("#{::Warrant.config.api_base}/v1/warrants"), Util.normalize_params(params))
 
             case res
@@ -75,28 +88,34 @@ module Warrant
             end
         end
 
-        # List all warrants for your organization.
+        # Query to find all warrants for a given subject.
         #
-        # @option filters [String] :object_type The type of object. Must be one of your system's existing object types. (optional)
-        # @option filters [String] :object_id The id of the specific object. (optional)
-        # @option filters [String] :relation The relation for this object to subject association. The relation must be valid as per the object type definition. (optional)
+        # @option params [String] :object_type The type of object. Must be one of your system's existing object types. (optional)
+        # @option params [String] :relation The relation for this object to subject association. The relation must be valid as per the object type definition. (optional)
+        # @option params [String] :subject The subject to query warrants for. This should be in the format `OBJECT_TYPE:OBJECT_ID`, i.e. `user:8`
+        #   * subject (Hash) - The specific subject for which warrants will be queried for.
+        #       * object_type (String) - The type of object. Must be one of your system's existing object types.
+        #       * object_id (String) - The id of the specific object.
+        # @option params [Integer] :page A positive integer (starting with 1) representing the page of items to return in response. Used in conjunction with the limit param. (optional)
+        # @option params [Integer] :limit A positive integer representing the max number of items to return in response. (optional)
         #
-        # @return [Array<Warrant>] list of all warrants with provided filters
+        # @return [Array<Warrant>] list of all warrants with provided params
         #
         # @raise [Warrant::InternalError]
-        # @raise [Warrant::InvalidRequestError]
-        # @raise [Warrant::NotFoundError]
+        # @raise [Warrant::InvalidParameterError]
+        # @raise [Warrant::MissingRequiredParameterError]
         # @raise [Warrant::UnauthorizedError]
         # @raise [Warrant::WarrantError]
-        def self.list(filters = {})
-            res = APIOperations.get(URI.parse("#{::Warrant.config.api_base}/v1/warrants"), filters)
+        def self.query(params = {})
+            params[:subject] = Subject.new_from_hash(params[:subject])
+            res = APIOperations.get(URI.parse("#{::Warrant.config.api_base}/v1/query"), params)
 
             case res
             when Net::HTTPSuccess
                 warrants = JSON.parse(res.body)
                 warrants.map{ |warrant|
-                    subject = Subject.new(warrant['subject']['objectType'], warrant['subject']['objectId'])
-                    Warrant.new(warrant['objectType'], warrant['objectId'], warrant['relation'], subject)
+                    subject = Subject.new(warrant['subject']['objectType'], warrant['subject']['objectId'], warrant['subject']['relation'])
+                    Warrant.new(warrant['objectType'], warrant['objectId'], warrant['relation'], subject, warrant['context'], warrant['isDirectMatch'])
                 }
             else
                 APIOperations.raise_error(res)
@@ -115,7 +134,8 @@ module Warrant
         #       * object_type (String) - The type of object. Must be one of your system's existing object types.
         #       * object_id (String) - The id of the specific object.
         #       * relation (String) - The relation for this object to subject association. The relation must be valid as per the object type definition. (optional)
-        # @param consistentRead [Boolean] Boolean flag indicating whether or not to enforce strict consistency for this access check. Defaults to false. (optional)
+        # @param context [Hash] - Object containing key-value pairs that specifies the context the warrant should be checked in. (optional)
+        # @param consistent_read [Boolean] Boolean flag indicating whether or not to enforce strict consistency for this access check. Defaults to false. (optional)
         # @param debug [Boolean] Boolean flag indicating whether or not to return debug information for this access check. Defaults to false. (optional)
         #
         # @return [Boolean] whether or not the given access check is authorized
@@ -134,11 +154,8 @@ module Warrant
         #
         # @raise [Warrant::InternalError]
         # @raise [Warrant::InvalidParameterError]
-        # @raise [Warrant::InvalidRequestError]
-        # @raise [Warrant::MissingRequiredParameterError]
         # @raise [Warrant::NotFoundError]
         # @raise [Warrant::UnauthorizedError]
-        # @raise [Warrant::WarrantError]
         def self.is_authorized?(params = {})
             unless ::Warrant.config.authorize_endpoint.nil?
                 return edge_authorize?(params)
@@ -147,10 +164,142 @@ module Warrant
             return authorize?(params)
         end
 
+        # Checks whether a specified access check is authorized or not.
+        #
+        # @param object [WarrantObject] Object to check in the access check. Object must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`). The object type must be one of your system's existing object type.
+        # @param relation [String] The relation to check for this object to subject association. The relation must be valid as per the object type definition.
+        # @param subject [WarrantObject] Subject to check in the access check. Subject must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`).
+        # @option options [Hash] :context Object containing key-value pairs that specifies the context the warrant should be checked in. (optional) (optional)
+        # @option options [Boolean] :consistent_read Boolean flag indicating whether or not to enforce strict consistency for this access check. Defaults to false. (optional)
+        # @option options [Boolean] :debug Boolean flag indicating whether or not to return debug information for this access check. Defaults to false. (optional)
+        #
+        # @return [Boolean] whether or not the given access check is authorized
+        #
+        # @example Check whether the user has "viewer" relation to report. `Report` and `User` here are both classes in your application that include `WarrantObject`.
+        #   my_report = Report.get("some-report")
+        #   current_user = User.get("llm-128")
+        #   Warrant::Warrant.is_authorized?(my_report, "viewer", current_user)
+        #
+        # @raise [Warrant::InternalError]
+        # @raise [Warrant::InvalidParameterError]
+        # @raise [Warrant::NotFoundError]
+        # @raise [Warrant::UnauthorizedError]
+        def self.check(object, relation, subject, options = {})
+            if subject.instance_of?(Subject)
+                subject = {
+                    object_type: subject.object_type,
+                    object_id: subject.object_id,
+                    relation: subject.relation
+                }.compact!
+            else
+                subject = {
+                    object_type: subject.warrant_object_type,
+                    object_id: subject.warrant_object_id
+                }
+            end
+
+            unless ::Warrant.config.authorize_endpoint.nil?
+                return edge_authorize?(
+                    warrants: [{
+                        object_type: object.warrant_object_type,
+                        object_id: object.warrant_object_id,
+                        relation: relation,
+                        subject: subject,
+                        context: options[:context]
+                    }],
+                    consistent_read: options[:consistent_read],
+                    debug: options[:debug]
+                )
+            end
+
+            return authorize?(
+                warrants: [{
+                    object_type: object.warrant_object_type,
+                    object_id: object.warrant_object_id,
+                    relation: relation,
+                    subject: subject,
+                    context: options[:context]
+                }],
+                consistent_read: options[:consistent_read],
+                debug: options[:debug]
+            )
+        end
+
+        # Checks whether multiple access checks are authorized or not.
+        #
+        # @param op [String] Logical operator to perform on warrants. Can be 'anyOf' or 'allOf'.
+        # @param warrants [Array] Array of warrants to check access for.
+        #   * object (WarrantObject) - Object to check in the access check. Object must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`). The object type must be one of your system's existing object type.
+        #   * relation (String) - The relation to check for this object to subject association. The relation must be valid as per the object type definition.
+        #   * subject (WarrantObject) Subject to check in the access check. Subject must include WarrantObject module and implements its methods (`warrant_object_type` and `warrant_object_id`).
+        # @option options [Hash] :context Object containing key-value pairs that specifies the context the warrant should be checked in. (optional)
+        # @option options [Boolean] :consistent_read Boolean flag indicating whether or not to enforce strict consistency for this access check. Defaults to false. (optional)
+        # @option options [Boolean] :debug Boolean flag indicating whether or not to return debug information for this access check. Defaults to false. (optional)
+        #
+        # @return [Boolean] whether or not the given access check is authorized
+        #
+        # @example Check whether the current user has "viewer" relation to report and is a "member" of the customer account "superstore". `Report`, `CustomerAccount` and `User` here are all classes in your application that include `WarrantObject`.
+        #   my_report = Report.get("some-report")
+        #   customer_account = CustomerAccount.get("superstore")
+        #   current_user = User.get("llm-128")
+        #   Warrant::Warrant.check_many(
+        #       "allOf",
+        #       [
+        #           { object: my_report, relation: "viewer", subject: current_user },
+        #           { object: customer_account, relation: "member", subject: current_user }
+        #       ]
+        #   )
+        #
+        # @raise [Warrant::InternalError]
+        # @raise [Warrant::InvalidParameterError]
+        # @raise [Warrant::NotFoundError]
+        # @raise [Warrant::UnauthorizedError]
+        def self.check_many(op, warrants, options = {})
+            normalized_warrants = warrants.map do |warrant|
+                if warrant[:subject].instance_of?(Subject)
+                    subject = {
+                        object_type: warrant[:subject].object_type,
+                        object_id: warrant[:subject].object_id,
+                        relation: warrant[:subject].relation
+                    }.compact!
+                else
+                    subject = {
+                        object_type: warrant[:subject].warrant_object_type,
+                        object_id: warrant[:subject].warrant_object_id
+                    }
+                end
+
+                {
+                    object_type: warrant[:object].warrant_object_type,
+                    object_id: warrant[:object].warrant_object_id,
+                    relation: warrant[:relation],
+                    subject: subject,
+                    context: warrant[:context]
+                }
+            end
+
+            unless ::Warrant.config.authorize_endpoint.nil?
+                return edge_authorize?(
+                    op: op,
+                    warrants: normalized_warrants,
+                    consistent_read: options[:consistent_read],
+                    debug: options[:debug]
+                )
+            end
+
+            return authorize?(
+                op: op,
+                warrants: normalized_warrants,
+                consistent_read: options[:consistent_read],
+                debug: options[:debug]
+            )
+        end
+
         # Checks whether a given user has a given permission.
         #
         # @param user_id [String] Id of the user to check
         # @param permission_id [String] Id of the permission to check on the user
+        # @param context [Hash] - Object containing key-value pairs that specifies the context the warrant should be checked in. (optional)
         # @param consistentRead [Boolean] Boolean flag indicating whether or not to enforce strict consistency for this access check. Defaults to false. (optional)
         # @param debug [Boolean] Boolean flag indicating whether or not to return debug information for this access check. Defaults to false. (optional)
         #
@@ -158,11 +307,8 @@ module Warrant
         #
         # @raise [Warrant::InternalError]
         # @raise [Warrant::InvalidParameterError]
-        # @raise [Warrant::InvalidRequestError]
-        # @raise [Warrant::MissingRequiredParameterError]
         # @raise [Warrant::NotFoundError]
         # @raise [Warrant::UnauthorizedError]
-        # @raise [Warrant::WarrantError]
         def self.user_has_permission?(params = {})
             return is_authorized?(
                 warrants: [{
@@ -172,13 +318,47 @@ module Warrant
                     subject: {
                         object_type: "user",
                         object_id: params[:user_id]
-                    }
+                    },
+                    context: params[:context]
                 }],
                 consistentRead: params[:consistentRead],
                 debug: params[:debug]
             )
         end
 
+        # Checks whether a given subject has a given feature.
+        #
+        # @param subject (Hash) - The specific subject for which feature access will be checked.
+        #   * object_type (String) - The type of object. Must be one of your system's existing object types.
+        #   * object_id (String) - The id of the specific object.
+        # @param feature_id [String] Id of the feature to check on the subject
+        # @param context [Hash] - Object containing key-value pairs that specifies the context the warrant should be checked in. (optional)
+        # @param consistent_read [Boolean] Boolean flag indicating whether or not to enforce strict consistency for this access check. Defaults to false. (optional)
+        # @param debug [Boolean] Boolean flag indicating whether or not to return debug information for this access check. Defaults to false. (optional)
+        #
+        # @return [Boolean] whether or not the user has the given permission
+        #
+        # @raise [Warrant::InternalError]
+        # @raise [Warrant::InvalidParameterError]
+        # @raise [Warrant::NotFoundError]
+        # @raise [Warrant::UnauthorizedError]
+        def self.has_feature?(params = {})
+            return is_authorized?(
+                warrants: [{
+                    object_type: "feature",
+                    object_id: params[:feature_id],
+                    relation: "member",
+                    subject: {
+                        object_type: params[:subject][:object_type],
+                        object_id: params[:subject][:object_id]
+                    },
+                    context: params[:context]
+                }],
+                consistent_read: params[:consistent_read],
+                debug: params[:debug]
+            )
+        end
+
         private
 
         def self.authorize?(params = {})

data/lib/warrant/util.rb

@@ -15,26 +15,29 @@ module Warrant
                     .downcase
             end
 
-            def normalize_options(opts)
-                new_opts = opts.each_with_object({}) do |(k, v), new_opts|
-                    new_key = Util.camelcase(k.to_s)
-
-                    new_opts[new_key] = v
-                end
-            end
-
             def normalize_params(params)
-                new_opts = params.each_with_object({}) do |(k, v), new_opts|
-                    new_key = Util.camelcase(k.to_s)
+                params.compact!
+
+                case params
+                when Hash
+                    params.each_with_object({}) do |(k, v), new_opts|
+                        new_key = Util.camelcase(k.to_s)
 
-                    case v
-                    when Hash
-                        new_opts[new_key] = normalize_params(v)
-                    when Array
-                        new_opts[new_key] = v.map { |i| normalize_params(i) }
-                    else
-                        new_opts[new_key] = v
+                        case v
+                        when Hash
+                            new_opts[new_key] = normalize_params(v)
+                        when Array
+                            new_opts[new_key] = v.map { |i| normalize_params(i) }
+                        when Subject
+                            new_opts[new_key] = "#{v.object_type}:#{v.object_id}"
+                        else
+                            new_opts[new_key] = v
+                        end
                     end
+                when Array
+                    params.map { |i| normalize_params(i) }
+                else
+                    params
                 end
             end
         end

data/lib/warrant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Warrant
-  VERSION = "1.1.0"
+  VERSION = "2.0.0.rc1"
 end

data/lib/warrant/warrant_configuration.rb

@@ -3,13 +3,13 @@
 module Warrant
     # @!visibility private
     class WarrantConfiguration
-        attr_accessor :api_key
-        attr_accessor :authorize_endpoint
+        attr_accessor :api_key, :api_base, :authorize_endpoint
 
-        attr_reader :api_base, :self_service_dash_url_base
+        attr_reader :self_service_dash_url_base
 
         def initialize
             @api_base = "https://api.warrant.dev"
+            @authorize_endpoint = "https://api.warrant.dev"
             @self_service_dash_url_base = "https://self-serve.warrant.dev"
         end
     end

data/lib/warrant/warrant_object.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Warrant
+    module WarrantObject
+        def warrant_object_type
+            raise "IMPLEMENT OBJECT TYPE!"
+        end
+
+        def warrant_object_id
+            raise "IMPLEMENT OBJECT ID!"
+        end
+    end
+end

data/lib/warrant.rb

@@ -6,9 +6,13 @@ require "net/http"
 require "json"
 require "forwardable"
 
+require "warrant/warrant_object"
+
 require "warrant/api_operations"
 require "warrant/errors"
+require "warrant/models/feature"
 require "warrant/models/permission"
+require "warrant/models/pricing_tier"
 require "warrant/models/role"
 require "warrant/models/session"
 require "warrant/models/subject"
@@ -26,6 +30,6 @@ module Warrant
 
         attr_reader :config
 
-        def_delegators :@config, :api_key, :api_key=, :authorize_endpoint, :authorize_endpoint=
+        def_delegators :@config, :api_key, :api_key=, :api_base, :api_base=, :authorize_endpoint, :authorize_endpoint=
     end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: warrant
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0.rc1
 platform: ruby
 authors:
 - Warrant
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-15 00:00:00.000000000 Z
+date: 2022-12-21 00:00:00.000000000 Z
 dependencies: []
 description: Ruby library for the Warrant API at https://warrant.dev.
 email: hello@warrant.dev
@@ -28,7 +28,9 @@ files:
 - lib/warrant.rb
 - lib/warrant/api_operations.rb
 - lib/warrant/errors.rb
+- lib/warrant/models/feature.rb
 - lib/warrant/models/permission.rb
+- lib/warrant/models/pricing_tier.rb
 - lib/warrant/models/role.rb
 - lib/warrant/models/session.rb
 - lib/warrant/models/subject.rb
@@ -38,6 +40,7 @@ files:
 - lib/warrant/util.rb
 - lib/warrant/version.rb
 - lib/warrant/warrant_configuration.rb
+- lib/warrant/warrant_object.rb
 homepage: https://github.com/warrant-dev/warrant-ruby
 licenses:
 - MIT
@@ -57,11 +60,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.3.11
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: Warrant Ruby Library