oso-oso 0.20.0.pre.beta → 0.20.1.pre.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa0564b86f2ceb4b54a62cdbae1cf2a3cc14ee91
-  data.tar.gz: d0cbc579ac5bd7284b559d3ca3d31af9f6837e96
+  metadata.gz: 7a6c6bd2d2fb38245a5103c0153f943f51060c90
+  data.tar.gz: 33dcb41c1c6bd0aeeec56d88391e1e80a66b6061
 SHA512:
-  metadata.gz: d2a7f469cff84febf8dd66f737384523fd576d42b1d44e41247bb738a7b26ca230d9e91066be2acf2a6ade07be780aeec5fa529b21c88c7d0bb626ca66ab821a
-  data.tar.gz: 742452956eeb29797b173888a268962bbc6e92e88b7148e7ca3952bb9d9c7687abd55d74c657d170056a61e911ed0183d29fa3ef471aa5c8cd733f47d72d188b
+  metadata.gz: 5c025329ad3a4eff57b2cf5e7d5ca8430ef825ee287111690f06439a7c6f623068048d27ea70358af8ffb8f9d935b926cdecf54baa848f95da9ebaa23b0c0e39
+  data.tar.gz: 2c4a4114eafb5887805a7b92015f466296ae9eaaa4ffe19f1cc60d4f2ec59b6b580ff80ebe60143e639d7f606d79f343c89e3fdd7e7a52789939af9716b9b2c3

data/.rubocop.yml

@@ -1,7 +1,7 @@
 AllCops:
   TargetRubyVersion: 2.4
   Exclude:
-    - '**/*~'
-    - 'bin/oso'
-    - 'vendor/**/*'
+    - "**/*~"
+    - "bin/oso"
+    - "vendor/**/*"
   NewCops: enable

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    oso-oso (0.20.0.pre.beta)
+    oso-oso (0.20.1.pre.beta)
       ffi (~> 1.0)
 
 GEM
@@ -19,15 +19,15 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
     arel (9.0.0)
-    ast (2.4.1)
-    backport (1.1.2)
-    benchmark (0.1.0)
+    ast (2.4.2)
+    backport (1.2.0)
+    benchmark (0.1.1)
     byebug (11.1.3)
     coderay (1.1.3)
     concurrent-ruby (1.1.9)
     diff-lcs (1.4.4)
     e2mmap (0.1.0)
-    ffi (1.15.3)
+    ffi (1.15.4)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.4)
@@ -37,8 +37,8 @@ GEM
     minitest (5.14.4)
     nokogiri (1.10.10)
       mini_portile2 (~> 2.4.0)
-    parallel (1.19.2)
-    parser (2.7.1.4)
+    parallel (1.20.1)
+    parser (2.7.2.0)
       ast (~> 2.4.1)
     pry (0.13.1)
       coderay (~> 1.1)
@@ -48,23 +48,23 @@ GEM
       pry (~> 0.13.0)
     rainbow (3.0.0)
     rake (12.3.3)
-    regexp_parser (1.7.1)
+    regexp_parser (2.1.1)
     reverse_markdown (2.0.0)
       nokogiri
-    rexml (3.2.4)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
     rubocop (0.89.1)
       parallel (~> 1.10)
       parser (>= 2.7.1.1)
@@ -74,10 +74,10 @@ GEM
       rubocop-ast (>= 0.3.0, < 1.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (0.3.0)
-      parser (>= 2.7.1.4)
-    ruby-progressbar (1.10.1)
-    solargraph (0.39.14)
+    rubocop-ast (0.8.0)
+      parser (>= 2.7.1.5)
+    ruby-progressbar (1.11.0)
+    solargraph (0.39.17)
       backport (~> 1.1)
       benchmark
       bundler (>= 1.17.2)
@@ -92,16 +92,17 @@ GEM
       tilt (~> 2.0)
       yard (~> 0.9, >= 0.9.24)
     sqlite3 (1.4.2)
-    thor (1.0.1)
+    thor (1.1.0)
     thread_safe (0.3.6)
     tilt (2.0.10)
     tzinfo (1.2.9)
       thread_safe (~> 0.1)
     unicode-display_width (1.7.0)
-    yard (0.9.25)
+    yard (0.9.26)
 
 PLATFORMS
   ruby
+  x86_64-darwin-20
 
 DEPENDENCIES
   activerecord
@@ -115,4 +116,4 @@ DEPENDENCIES
   yard (~> 0.9.25)
 
 BUNDLED WITH
-   2.2.4
+   2.2.15

data/README.md

@@ -4,9 +4,7 @@
 
 Add this line to your application's Gemfile:
 
-```ruby
-gem 'oso-oso'
-```
+    gem 'oso-oso'
 
 And then execute:
 

data/lib/oso/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Oso
+  class Error < ::RuntimeError
+  end
+
+  class AuthorizationError < Error
+  end
+
+  # Thrown by the +authorize+, +authorize_field+, and +authorize_request+
+  # methods when the action is not allowed.
+  #
+  # Most of the time, your app should handle this error by returning a 403 HTTP
+  # error to the client.
+  class ForbiddenError < AuthorizationError
+    def initialize
+      super(
+        'Oso ForbiddenError -- The requested action was not allowed for the ' \
+        'given resource. You should handle this error by returning a 403 error ' \
+        'to the client.'
+      )
+    end
+  end
+
+  # Thrown by the +authorize+ method of an +Oso+ instance. This error indicates
+  # that the actor is not only not allowed to perform the given action, but also
+  # is not allowed to +"read"+ the given resource.
+  #
+  # Most of the time, your app should handle this error by returning a 404 HTTP
+  # error to the client.
+  #
+  # To control which action is used for the distinction between
+  # +NotFoundError+ and +ForbiddenError+, you can customize the
+  # +read_action+ on your +Oso+ instance.
+  class NotFoundError < AuthorizationError
+    def initialize
+      super(
+        'Oso NotFoundError -- The current user does not have permission to read ' \
+        'the given resource. You should handle this error by returning a 404 ' \
+        'error to the client.'
+      )
+    end
+  end
+end

data/lib/oso/oso.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
+require 'set'
 require_relative 'polar/polar'
 
 module Oso
   # oso authorization API.
   class Oso < Polar::Polar
-    def initialize
-      super
+    # Create an Oso instance, which is used to configure and enforce an Oso
+    # policy in an app.
+    #
+    # @param forbidden_error [Class] Optionally override the "forbidden" error
+    #   class thrown by the `authorize*` methods. Defaults to
+    #   {Oso::ForbiddenError}.
+    # @param not_found_error [Class] Optionally override the "not found" error
+    #   class thrown by {#authorize}. Defaults to {Oso::NotFoundError}.
+    # @param read_action The action used by the {#authorize} method to
+    #   determine whether an authorization failure should
+    #   raise a {Oso::NotFoundError} or a {Oso::ForbiddenError}
+    def initialize(not_found_error: NotFoundError, forbidden_error: ForbiddenError, read_action: 'read')
+      super()
+      @not_found_error = not_found_error
+      @forbidden_error = forbidden_error
+      @read_action = read_action
     end
 
     # Query the knowledge base to determine whether an actor is allowed to
@@ -17,7 +32,191 @@ module Oso
     # @param resource [Object] Object.
     # @return [Boolean] An access control decision.
     def allowed?(actor:, action:, resource:)
-      !query_rule('allow', actor, action, resource).first.nil?
+      query_rule_once('allow', actor, action, resource)
+    end
+
+    # Ensure that +actor+ is allowed to perform +action+ on
+    # +resource+.
+    #
+    # If the action is permitted with an +allow+ rule in the policy, then
+    # this method returns +None+. If the action is not permitted by the
+    # policy, this method will raise an error.
+    #
+    # The error raised by this method depends on whether the actor can perform
+    # the +"read"+ action on the resource. If they cannot read the resource,
+    # then a {Oso::NotFoundError} error is raised. Otherwise, a
+    # {Oso::ForbiddenError} is raised.
+    #
+    # @param actor The actor performing the request.
+    # @param action The action the actor is attempting to perform.
+    # @param resource The resource being accessed.
+    # @param check_read [Boolean] If set to +false+, a {Oso::ForbiddenError} is
+    #   always thrown on authorization failures, regardless of whether the actor
+    #   can read the resource. Default is +true+.
+    #
+    # @raise [Oso::ForbiddenError] Raised if the actor does not have permission
+    #   to perform this action on this resource, but _does_ have +"read"+
+    #   permission on the resource.
+    # @raise [Oso::NotFoundError] Raised if the actor does not have permission
+    #   to perform this action on this resource and additionally does not have
+    #   permission to +"read"+ the resource.
+    def authorize(actor, action, resource, check_read: true)
+      return if query_rule_once('allow', actor, action, resource)
+
+      if check_read && (action == @read_action || !query_rule_once('allow', actor, @read_action, resource))
+        raise @not_found_error
+      end
+
+      raise @forbidden_error
+    end
+
+    # Ensure that +actor+ is allowed to send +request+ to the server.
+    #
+    # Checks the +allow_request+ rule of a policy.
+    #
+    # If the request is permitted with an +allow_request+ rule in the
+    # policy, then this method returns nothing. Otherwise, this method raises
+    # a {Oso::ForbiddenError}.
+    #
+    # @param actor The actor performing the request.
+    # @param request An object representing the request that was sent by the
+    #   actor.
+    #
+    # @raise [Oso::ForbiddenError] Raised if the actor does not have permission
+    #   to send the request.
+    def authorize_request(actor, request)
+      raise @forbidden_error unless query_rule_once('allow_request', actor, request)
+    end
+
+    # Ensure that +actor+ is allowed to perform +action+ on a given
+    # +resource+'s +field+.
+    #
+    # If the action is permitted by an +allow_field+ rule in the policy,
+    # then this method returns nothing. If the action is not permitted by the
+    # policy, this method will raise a {Oso::ForbiddenError}.
+    #
+    # @param actor The actor performing the request.
+    # @param action The action the actor is attempting to perform on the
+    #   field.
+    # @param resource The resource being accessed.
+    # @param field The name of the field being accessed.
+    #
+    # @raise [Oso::ForbiddenError] Raised if the actor does not have permission
+    #   to access this field.
+    def authorize_field(actor, action, resource, field)
+      raise @forbidden_error unless query_rule_once('allow_field', actor, action, resource, field)
+    end
+
+    # Determine the actions +actor+ is allowed to take on +resource+.
+    #
+    # Collects all actions allowed by allow rules in the Polar policy for the
+    # given combination of actor and resource.
+    #
+    # @param actor The actor for whom to collect allowed actions
+    # @param resource The resource being accessed
+    # @param allow_wildcard Flag to determine behavior if the policy
+    #   includes a wildcard action. E.g., a rule allowing any action:
+    #   +allow(_actor, _action, _resource)+. If +true+, the method will
+    #   return +Set["*"]+, if +false+, the method will raise an exception.
+    # @return A set of the unique allowed actions.
+    def authorized_actions(actor, resource, allow_wildcard: false) # rubocop:disable Metrics/MethodLength
+      results = query_rule('allow', actor, Polar::Variable.new('action'), resource)
+      actions = Set.new
+      results.each do |result|
+        action = result['action']
+        if action.is_a?(Polar::Variable)
+          return Set['*'] if allow_wildcard
+
+          raise ::Oso::Error,
+                'The result of authorized_actions() contained an '\
+                '"unconstrained" action that could represent any '\
+                'action, but allow_wildcard was set to False. To fix, '\
+                'set allow_wildcard to True and compare with the "*" '\
+                'string.'
+        end
+        actions.add(action)
+      end
+      actions
+    end
+
+    # Determine the fields of +resource+ on which +actor+ is allowed to
+    # perform  +action+.
+    #
+    # Uses +allow_field+ rules in the policy to find all allowed fields.
+    #
+    # @param actor The actor for whom to collect allowed fields.
+    # @param action The action being taken on the field.
+    # @param resource The resource being accessed.
+    # @param allow_wildcard Flag to determine behavior if the policy \
+    #   includes a wildcard field. E.g., a rule allowing any field: \
+    #   +allow_field(_actor, _action, _resource, _field)+. If +true+, the \
+    #   method will return +Set["*"]+, if +false+, the method will raise an \
+    #   exception.
+    # @return A set of the unique allowed fields.
+    def authorized_fields(actor, action, resource, allow_wildcard: false) # rubocop:disable Metrics/MethodLength
+      results = query_rule('allow_field', actor, action, resource, Polar::Variable.new('field'))
+      fields = Set.new
+      results.each do |result|
+        field = result['field']
+        if field.is_a?(Polar::Variable)
+          return Set['*'] if allow_wildcard
+
+          raise ::Oso::Error,
+                'The result of authorized_fields() contained an '\
+                '"unconstrained" field that could represent any '\
+                'field, but allow_wildcard was set to False. To fix, '\
+                'set allow_wildcard to True and compare with the "*" '\
+                'string.'
+        end
+        fields.add(field)
+      end
+      fields
+    end
+
+    # Returns a query for resources of type +cls+ that +actor+  is allowed
+    # to perform +action+ on.
+    #
+    # @param actor The actor whose permissions to check.
+    # @param action The action being taken on the resource.
+    # @param resource_cls The resource being accessed.
+    #
+    # @returns A query for resources accessible to the actor.
+    def authorized_query(actor, action, resource_cls) # rubocop:disable Metrics/MethodLength
+      resource = Polar::Variable.new 'resource'
+
+      results = query_rule(
+        'allow',
+        actor,
+        action,
+        resource,
+        bindings: { 'resource' => type_constraint(resource, resource_cls) },
+        accept_expression: true
+      )
+
+      results = results.each_with_object([]) do |result, out|
+        result.each do |key, val|
+          out.push({ 'bindings' => { key => host.to_polar(val) } })
+        end
+      end
+
+      ::Oso::Polar::DataFiltering::FilterPlan
+        .parse(self, results, get_class_name(resource_cls))
+        .build_query
+    end
+
+    # Returns the resources of type +resource_cls+ that +actor+  is allowed
+    # to perform +action+ on.
+    #
+    # @param actor The actor whose permissions to check.
+    # @param action The action being taken on the resource.
+    # @param resource_cls The resource being accessed.
+    #
+    # @returns A list of resources accessible to the actor.
+    def authorized_resources(actor, action, resource_cls)
+      q = authorized_query actor, action, resource_cls
+      return [] if q.nil?
+
+      host.types[get_class_name resource_cls].exec_query[q]
     end
   end
 end

data/lib/oso/polar/data_filtering.rb

@@ -7,62 +7,84 @@ module Oso
       # Represents a set of filter sequences that should allow the host
       # to obtain the records satisfying a query.
       class FilterPlan
-        include Enumerable
         attr_reader :result_sets
 
-        def initialize(polar, partials, class_name)
+        def self.parse(polar, partials, class_name)
           types = polar.host.serialize_types
           parsed_json = polar.ffi.build_filter_plan(types, partials, 'resource', class_name)
-          @polar = polar
-          @result_sets = parsed_json['result_sets'].map do |rset|
-            ResultSet.new polar, rset
+          result_sets = parsed_json['result_sets'].map do |rset|
+            ResultSet.parse polar, rset
           end
+
+          new polar: polar, result_sets: result_sets
         end
 
-        def each(&blk)
-          result_sets.each(&blk)
+        def initialize(polar:, result_sets:)
+          @polar = polar
+          @result_sets = result_sets
         end
 
-        def resolve # rubocop:disable Metrics/AbcSize
-          reduce([]) do |acc, rs|
-            requests = rs.requests
-            acc + rs.resolve_order.each_with_object({}) do |i, set_results|
-              req = requests[i]
-              constraints = req.constraints
-              constraints.each { |c| c.ground set_results }
-              set_results[i] = @polar.host.types[req.class_tag].fetcher[constraints]
-            end[rs.result_id]
-          end.uniq
+        def build_query # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          combine = nil
+          result_sets.each_with_object([]) do |rs, qb|
+            rs.resolve_order.each_with_object({}) do |i, set_results|
+              req = rs.requests[i]
+              cs = req.constraints.each { |c| c.ground set_results }
+              typ = @polar.host.types[req.class_tag]
+              q = typ.build_query[cs]
+              if i != rs.result_id
+                set_results[i] = typ.exec_query[q]
+              else
+                combine = typ.combine_query
+                qb.push q
+              end
+            end
+          end.reduce(&combine)
         end
 
         # Represents a sequence of filters for one set of results
         class ResultSet
           attr_reader :requests, :resolve_order, :result_id
 
-          def initialize(polar, parsed_json)
-            @resolve_order = parsed_json['resolve_order']
-            @result_id = parsed_json['result_id']
-            @requests = parsed_json['requests'].each_with_object({}) do |req, reqs|
-              reqs[req[0].to_i] = Request.new(polar, req[1])
+          def self.parse(polar, parsed_json)
+            resolve_order = parsed_json['resolve_order']
+            result_id = parsed_json['result_id']
+            requests = parsed_json['requests'].each_with_object({}) do |req, reqs|
+              reqs[req[0].to_i] = Request.parse(polar, req[1])
             end
+
+            new resolve_order: resolve_order, result_id: result_id, requests: requests
+          end
+
+          def initialize(requests:, resolve_order:, result_id:)
+            @resolve_order = resolve_order
+            @requests = requests
+            @result_id = result_id
           end
+        end
 
-          # Represents a filter for a result set
-          class Request
-            attr_reader :constraints, :class_tag
+        # Represents a filter for a result set
+        class Request
+          attr_reader :constraints, :class_tag
 
-            def initialize(polar, parsed_json)
-              @constraints = parsed_json['constraints'].map do |con|
-                Constraint.parse polar, con
-              end
-              @class_tag = parsed_json['class_tag']
+          def self.parse(polar, parsed_json)
+            constraints = parsed_json['constraints'].map do |con|
+              Filter.parse polar, con
             end
+            class_tag = parsed_json['class_tag']
+
+            new(constraints: constraints, class_tag: class_tag)
+          end
+
+          def initialize(constraints:, class_tag:)
+            @constraints = constraints
+            @class_tag = class_tag
           end
         end
       end
 
-      # Represents relationships between resources, eg. parent/child
-      class Relationship
+      # Represents relationships between resources, eg. one-one or one-many
+      class Relation
         attr_reader :kind, :other_type, :my_field, :other_field
 
         def initialize(kind:, other_type:, my_field:, other_field:)
@@ -93,12 +115,13 @@ module Oso
       end
 
       # Represents a condition that must hold on a resource.
-      class Constraint
+      class Filter
         attr_reader :kind, :field, :value
 
         CHECKS = {
           'Eq' => ->(a, b) { a == b },
           'In' => ->(a, b) { b.include? a },
+          'Neq' => ->(a, b) { a != b },
           'Contains' => ->(a, b) { a.include? b }
         }.freeze
 
@@ -126,8 +149,6 @@ module Oso
 
         def self.parse(polar, constraint) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           kind = constraint['kind']
-          raise unless %w[Eq In Contains].include? kind
-
           field = constraint['field']
           value = constraint['value']
 

data/lib/oso/polar/errors.rb

@@ -3,7 +3,7 @@
 module Oso
   module Polar
     # Base error type for Oso::Polar.
-    class Error < ::RuntimeError
+    class Error < ::Oso::Error
       attr_reader :stack_trace
 
       # @param message [String]
@@ -68,7 +68,7 @@ module Oso
       end
     end
     class DuplicateClassAliasError < PolarRuntimeError # rubocop:disable Style/Documentation
-      # @param as [String]
+      # @param name [String]
       # @param old [Class]
       # @param new [Class]
       def initialize(name:, old:, new:)
@@ -101,7 +101,6 @@ module Oso
     class ParameterError < ApiError; end
 
     class ValidationError < Error; end
-    class RolesValidationError < Error; end
 
     UNEXPECTED_EXPRESSION_MESSAGE = <<~MSG
       Received Expression from Polar VM. The Expression type is not yet supported in this language.

data/lib/oso/polar/ffi/error.rb

@@ -56,7 +56,7 @@ module Oso
             operational_error(subkind, msg: msg, details: details)
           when 'Parameter'
             api_error(subkind, msg: msg, details: details)
-          when 'RolesValidation'
+          when 'Validation'
             validation_error(msg, details: details)
           end
         end
@@ -146,7 +146,7 @@ module Oso
         # @return [::Oso::Polar::ValidationError] the object converted into the expected format.
         private_class_method def self.validation_error(msg, details:)
           # This is currently the only type of validation error.
-          ::Oso::Polar::RolesValidationError.new(msg, details: details)
+          ::Oso::Polar::ValidationError.new(msg, details: details)
         end
       end
     end

data/lib/oso/polar/ffi/polar.rb

@@ -14,15 +14,14 @@ module Oso
           ffi_lib FFI::LIB_PATH
 
           attach_function :new, :polar_new, [], FFI::Polar
-          attach_function :enable_roles, :polar_enable_roles, [FFI::Polar], :int32
-          attach_function :validate_roles_config, :polar_validate_roles_config, [FFI::Polar, :string], :int32
-          attach_function :load, :polar_load, [FFI::Polar, :string, :string], :int32
+          attach_function :load, :polar_load, [FFI::Polar, :string], :int32
           attach_function :clear_rules, :polar_clear_rules, [FFI::Polar], :int32
           attach_function :next_inline_query, :polar_next_inline_query, [FFI::Polar, :uint32], FFI::Query
           attach_function :new_id, :polar_get_external_id, [FFI::Polar], :uint64
           attach_function :new_query_from_str, :polar_new_query, [FFI::Polar, :string, :uint32], FFI::Query
           attach_function :new_query_from_term, :polar_new_query_from_term, [FFI::Polar, :string, :uint32], FFI::Query
           attach_function :register_constant, :polar_register_constant, [FFI::Polar, :string, :string], :int32
+          attach_function :register_mro, :polar_register_mro, [FFI::Polar, :string, :string], :int32
           attach_function :next_message, :polar_next_polar_message, [FFI::Polar], FFI::Message
           attach_function :free, :polar_free, [FFI::Polar], :int32
           attach_function(
@@ -43,20 +42,6 @@ module Oso
           polar
         end
 
-        # @raise [FFI::Error] if the FFI call returns an error.
-        def enable_roles
-          result = Rust.enable_roles(self)
-          process_messages
-          handle_error if result.zero?
-        end
-
-        # @raise [FFI::Error] if the FFI call returns an error.
-        def validate_roles_config(config)
-          result = Rust.validate_roles_config(self, JSON.dump(config))
-          process_messages
-          handle_error if result.zero?
-        end
-
         def build_filter_plan(types, partials, variable, class_tag)
           types = JSON.dump(types)
           partials = JSON.dump(partials)
@@ -67,11 +52,10 @@ module Oso
           JSON.parse plan
         end
 
-        # @param src [String]
-        # @param filename [String]
+        # @param sources [Array<Source>]
         # @raise [FFI::Error] if the FFI call returns an error.
-        def load(src, filename: nil)
-          loaded = Rust.load(self, src, filename)
+        def load(sources)
+          loaded = Rust.load(self, JSON.dump(sources))
           process_messages
           handle_error if loaded.zero?
         end
@@ -133,6 +117,14 @@ module Oso
           handle_error if registered.zero?
         end
 
+        # @param name [String]
+        # @param mro [Array<Integer>]
+        # @raise [FFI::Error] if the FFI call returns an error.
+        def register_mro(name, mro)
+          registered = Rust.register_mro(self, name, JSON.dump(mro))
+          handle_error if registered.zero?
+        end
+
         def next_message
           Rust.next_message(self)
         end

data/lib/oso/polar/ffi/query.rb

@@ -50,8 +50,7 @@ module Oso
           handle_error if res.zero?
         end
 
-        # @param result [Boolean]
-        # @param call_id [Integer]
+        # @param message [String]
         # @raise [FFI::Error] if the FFI call returns an error.
         def application_error(message)
           res = Rust.application_error(self, message)

data/lib/oso/polar/host.rb

@@ -36,21 +36,23 @@ module Oso
 
     # For holding type metadata: name, fields, etc.
     class UserType
-      attr_reader :name, :klass, :id, :fields, :fetcher
+      attr_reader :name, :klass, :id, :fields, :build_query, :combine_query, :exec_query
 
-      def initialize(name:, klass:, id:, fields:, fetcher:)
+      def initialize(name:, klass:, id:, fields:, build_query:, combine_query:, exec_query:) # rubocop:disable Metrics/ParameterLists
         @name = name
         @klass = klass
         @id = id
         # accept symbol keys
         @fields = fields.each_with_object({}) { |kv, o| o[kv[0].to_s] = kv[1] }
-        @fetcher = fetcher
+        @build_query = build_query
+        @combine_query = combine_query
+        @exec_query = exec_query
       end
     end
 
     # Translate between Polar and the host language (Ruby).
     class Host # rubocop:disable Metrics/ClassLength
-      # @return [Hash<String, Class>]
+      # @return [Hash<String, UserType>]
       attr_reader :types
 
       protected
@@ -97,19 +99,31 @@ module Oso
       # @return [String] the name the class is cached as.
       # @raise [DuplicateClassAliasError] if attempting to register a class
       # under a previously-registered name.
-      def cache_class(cls, name:, fields: {}, fetcher: nil)
+      def cache_class(cls, name:, fields:, build_query:, combine_query:, exec_query:) # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
         raise DuplicateClassAliasError.new name: name, old: get_class(name), new: cls if types.key? name
 
         types[name] = types[cls] = UserType.new(
           name: name,
           klass: PolarClass.new(cls),
           id: cache_instance(cls),
-          fields: fields,
-          fetcher: fetcher
+          fields: fields || {},
+          combine_query: combine_query,
+          exec_query: exec_query,
+          build_query: build_query
         )
         name
       end
 
+      def register_mros # rubocop:disable Metrics/AbcSize
+        types.values.uniq.each do |typ|
+          mro = []
+          typ.klass.get.ancestors.each do |a|
+            mro.push(types[a].id) if types.key?(a)
+          end
+          ffi_polar.register_mro(typ.name, mro)
+        end
+      end
+
       # Check if an instance exists in the {#instances} cache.
       #
       # @param id [Integer]
@@ -181,7 +195,7 @@ module Oso
 
       # Compare two values
       #
-      # @param op [String] operation to perform.
+      # @param operation [String] operation to perform.
       # @param args [Array<Object>] left and right args to operation.
       # @raise [PolarRuntimeError] if operation fails or is unsupported.
       # @return [Boolean]
@@ -234,9 +248,9 @@ module Oso
           field_types = {}
           fields.each do |k, v|
             field_types[k] =
-              if v.is_a? ::Oso::Polar::DataFiltering::Relationship
+              if v.is_a? ::Oso::Polar::DataFiltering::Relation
                 {
-                  'Relationship' => {
+                  'Relation' => {
                     'kind' => v.kind,
                     'other_class_tag' => v.other_type,
                     'my_field' => v.my_field,
@@ -293,7 +307,9 @@ module Oso
                     { 'Pattern' => { 'Instance' => { 'tag' => value.tag, 'fields' => dict['Dictionary'] } } }
                   end
                 else
-                  { 'ExternalInstance' => { 'instance_id' => cache_instance(value), 'repr' => nil } }
+                  instance_id = nil
+                  instance_id = types[value].id if value.is_a?(Class) && types.key?(value)
+                  { 'ExternalInstance' => { 'instance_id' => cache_instance(value, id: instance_id), 'repr' => nil } }
                 end
         { 'value' => value }
       end

data/lib/oso/polar/polar.rb

@@ -27,6 +27,35 @@ def print_error(error)
   warn error.message
 end
 
+# Polar source string with optional filename.
+class Source
+  # @return [String]
+  attr_reader :src, :filename
+
+  # @param src [String]
+  # @param filename [String]
+  def initialize(src, filename: nil)
+    @src = src
+    @filename = filename
+  end
+
+  def to_json(*_args)
+    { src: src, filename: filename }.to_json
+  end
+end
+
+def filename_to_source(filename)
+  raise Oso::Polar::PolarFileExtensionError, filename unless File.extname(filename) == '.polar'
+
+  src = File.open(filename, &:read)
+
+  raise Oso::Polar::NullByteInPolarFileError if src.chomp("\0").include?("\0")
+
+  Source.new(src, filename: filename)
+rescue Errno::ENOENT
+  raise Oso::Polar::PolarFileNotFoundError, filename
+end
+
 module Oso
   module Polar
     # Create and manage an instance of the Polar runtime.
@@ -34,11 +63,10 @@ module Oso
       # @return [Host]
       attr_reader :host
 
-      def initialize # rubocop:disable Metrics/MethodLength
+      def initialize
         @ffi_polar = FFI::Polar.create
         @host = Host.new(ffi_polar)
         @ffi_polar.enrich_message = @host.method(:enrich_message)
-        @polar_roles_enabled = false
 
         # Register global constants.
         register_constant nil, name: 'nil'
@@ -56,42 +84,6 @@ module Oso
         @ffi_polar
       end
 
-      def enable_roles # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        return if polar_roles_enabled
-
-        roles_helper = Class.new do
-          def self.join(separator, left, right)
-            [left, right].join(separator)
-          end
-        end
-        register_constant(roles_helper, name: '__oso_internal_roles_helpers__')
-        ffi_polar.enable_roles
-        self.polar_roles_enabled = true
-
-        # validate config
-        validation_query_results = []
-        loop do
-          query = ffi_polar.next_inline_query
-          break if query.nil?
-
-          new_host = host.dup
-          new_host.accept_expression = true
-          results = Query.new(query, host: new_host).to_a
-          raise InlineQueryFailedError, query.source if results.empty?
-
-          validation_query_results.push results
-        end
-
-        # turn bindings back into polar
-        validation_query_results = validation_query_results.map do |results|
-          results.map do |result|
-            { 'bindings' => result.transform_values { |v| host.to_polar(v) } }
-          end
-        end
-
-        ffi_polar.validate_roles_config(validation_query_results)
-      end
-
       # get the (maybe user-supplied) name of a class.
       # kind of a hack because of class autoreloading.
       def get_class_name(klass) # rubocop:disable Metrics/AbcSize
@@ -108,61 +100,52 @@ module Oso
         end
       end
 
-      def get_allowed_resources(actor, action, klass) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        resource = Variable.new 'resource'
-        class_name = get_class_name klass
-        constraint = Expression.new(
-          'And',
-          [Expression.new('Isa', [resource, Pattern.new(class_name, {})])]
-        )
-
-        results = query_rule(
-          'allow',
-          actor,
-          action,
-          resource,
-          bindings: { 'resource' => constraint },
-          accept_expression: true
-        )
-
-        complete = []
-        partial = []
-
-        results.to_a.each do |result|
-          result.to_a.each do |key, val|
-            if val.is_a? Expression
-              partial.push({ 'bindings' => { key => host.to_polar(val) } })
-            else
-              complete.push val
-            end
-          end
-        end
-        filter = ::Oso::Polar::DataFiltering::FilterPlan.new(self, partial, class_name)
-        complete + filter.resolve
-      end
-
       # Clear all rules and rule sources from the current Polar instance
       #
       # @return [self] for chaining.
       def clear_rules
         ffi_polar.clear_rules
-        ffi_polar.enable_roles if polar_roles_enabled
         self
       end
 
-      # Load a Polar policy file.
+      # Load Polar policy files.
       #
-      # @param name [String]
-      # @raise [PolarFileExtensionError] if provided filename has invalid extension.
-      # @raise [PolarFileNotFoundError] if provided filename does not exist.
+      # @param filenames [Array<String>]
+      # @raise [PolarFileExtensionError] if any filename has an invalid extension.
+      # @raise [PolarFileNotFoundError] if any filename does not exist.
+      # @raise [NullByteInPolarFileError] if any file contains a non-terminating null byte.
+      # @raise [Error] if any of the FFI calls raise one.
+      # @raise [InlineQueryFailedError] on the first failed inline query.
       # @return [self] for chaining.
-      def load_file(name)
-        raise PolarFileExtensionError, name unless File.extname(name) == '.polar'
+      def load_files(filenames = [])
+        return if filenames.empty?
 
-        file_data = File.open(name, &:read)
-        load_str(file_data, filename: name)
-      rescue Errno::ENOENT
-        raise PolarFileNotFoundError, name
+        sources = filenames.map { |f| filename_to_source f }
+        load_sources(sources)
+        self
+      end
+
+      # Load a Polar policy file.
+      #
+      # @param filename [String]
+      # @raise [PolarFileExtensionError] if filename has an invalid extension.
+      # @raise [PolarFileNotFoundError] if filename does not exist.
+      # @raise [NullByteInPolarFileError] if file contains a non-terminating null byte.
+      # @raise [Error] if any of the FFI calls raise one.
+      # @raise [InlineQueryFailedError] on the first failed inline query.
+      # @return [self] for chaining.
+      #
+      # @deprecated {#load_file} has been deprecated in favor of {#load_files}
+      #   as of the 0.20.0 release. Please see changelog for migration
+      #   instructions:
+      #   https://docs.osohq.com/project/changelogs/2021-09-15.html
+      def load_file(filename)
+        warn <<~WARNING
+          `Oso#load_file` has been deprecated in favor of `Oso#load_files` as of the 0.20.0 release.
+
+          Please see changelog for migration instructions: https://docs.osohq.com/project/changelogs/2021-09-15.html
+        WARNING
+        load_files([filename])
       end
 
       # Load a Polar string into the KB.
@@ -170,26 +153,13 @@ module Oso
       # @param str [String] Polar string to load.
       # @param filename [String] Name of Polar source file.
       # @raise [NullByteInPolarFileError] if str includes a non-terminating null byte.
-      # @raise [InlineQueryFailedError] on the first failed inline query.
       # @raise [Error] if any of the FFI calls raise one.
+      # @raise [InlineQueryFailedError] on the first failed inline query.
       # @return [self] for chaining.
-      def load_str(str, filename: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def load_str(str, filename: nil)
         raise NullByteInPolarFileError if str.chomp("\0").include?("\0")
 
-        ffi_polar.load(str, filename: filename)
-        loop do
-          next_query = ffi_polar.next_inline_query
-          break if next_query.nil?
-
-          raise InlineQueryFailedError, next_query.source if Query.new(next_query, host: host).first.nil?
-        end
-
-        # If roles are enabled, re-validate config when new rules are loaded.
-        if polar_roles_enabled
-          self.polar_roles_enabled = false
-          enable_roles
-        end
-
+        load_sources([Source.new(str, filename: filename)])
         self
       end
 
@@ -227,6 +197,16 @@ module Oso
         query(Predicate.new(name, args: args), host: host, bindings: bindings)
       end
 
+      # Query for a rule, returning true if it has any results.
+      #
+      # @param name [String]
+      # @param args [Array<Object>]
+      # @return [Boolean] indicating whether the query found at least one result.
+      # @raise [Error] if the FFI call raises one.
+      def query_rule_once(name, *args)
+        query_rule(name, *args).any?
+      end
+
       # Register a Ruby class with Polar.
       #
       # @param cls [Class] the class to register.
@@ -235,8 +215,15 @@ module Oso
       # under a previously-registered name.
       # @raise [FFI::Error] if the FFI call returns an error.
       # @return [self] for chaining.
-      def register_class(cls, name: nil, fields: {}, fetcher: nil)
-        name = host.cache_class(cls, name: name || cls.name, fields: fields, fetcher: fetcher)
+      def register_class(cls, name: nil, fields: nil, combine_query: nil, build_query: nil, exec_query: nil) # rubocop:disable Metrics/ParameterLists
+        name = host.cache_class(
+          cls,
+          name: name || cls.name,
+          fields: fields,
+          build_query: build_query || maybe_mtd(cls, :build_query),
+          combine_query: combine_query || maybe_mtd(cls, :combine_query),
+          exec_query: exec_query || maybe_mtd(cls, :exec_query)
+        )
         register_constant(cls, name: name)
       end
 
@@ -256,7 +243,7 @@ module Oso
       # @param files [Array<String>]
       # @raise [Error] if the FFI call raises one.
       def repl(files = [])
-        files.map { |f| load_file(f) }
+        load_files(files)
         prompt = "#{FG_BLUE}query>#{RESET} "
         # Try loading the readline module from the Ruby stdlib. If we get a
         # LoadError, fall back to the standard REPL with no readline support.
@@ -268,9 +255,36 @@ module Oso
 
       private
 
+      def type_constraint(var, cls)
+        Expression.new(
+          'And',
+          [Expression.new('Isa', [var, Pattern.new(get_class_name(cls), {})])]
+        )
+      end
+
+      def maybe_mtd(cls, mtd)
+        cls.respond_to?(mtd) && cls.method(mtd) || nil
+      end
+
       # @return [FFI::Polar]
       attr_reader :ffi_polar
-      attr_accessor :polar_roles_enabled
+
+      # Register MROs, load Polar code, and check inline queries.
+      # @param sources [Array<Source>] Polar sources to load.
+      def load_sources(sources)
+        host.register_mros
+        ffi_polar.load(sources)
+        check_inline_queries
+      end
+
+      def check_inline_queries
+        loop do
+          next_query = ffi_polar.next_inline_query
+          break if next_query.nil?
+
+          raise InlineQueryFailedError, next_query.source if Query.new(next_query, host: host).none?
+        end
+      end
 
       # The R and L in REPL for systems where readline is available.
       def repl_readline(prompt)

data/lib/oso/polar/query.rb

@@ -18,6 +18,16 @@ module Oso
         bindings.each { |k, v| ffi_query.bind k, host.to_polar(v) }
       end
 
+      # Create an enumerator that can be polled to advance the query loop. Yields
+      # results one by one.
+      #
+      # @yieldparam [Hash<String, Object>]
+      # @return [Enumerator]
+      # @raise [Error] if any of the FFI calls raise one.
+      def each(&block)
+        run(&block)
+      end
+
       private
 
       # @return [Hash<Integer, Enumerator>]
@@ -65,10 +75,11 @@ module Oso
       # Fetch the next result from calling a Ruby method and prepare it for
       # transmission across the FFI boundary.
       #
-      # @param method [#to_sym]
-      # @param args [Array<Hash>]
+      # @param attribute [#to_sym]
       # @param call_id [Integer]
       # @param instance [Hash<String, Object>]
+      # @param args [Array<Hash>]
+      # @param kwargs [Hash<String, Object>]
       # @raise [Error] if the FFI call raises one.
       def handle_call(attribute, call_id:, instance:, args:, kwargs:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         instance = host.to_ruby(instance)
@@ -100,12 +111,12 @@ module Oso
         raise unless cls.fields.key? tag
 
         ref = cls.fields[tag]
-        return host.types[ref] unless ref.is_a? ::Oso::Polar::DataFiltering::Relationship
+        return host.types[ref] unless ref.is_a? ::Oso::Polar::DataFiltering::Relation
 
         case ref.kind
-        when 'parent'
+        when 'one'
           host.types[ref.other_type]
-        when 'children'
+        when 'many'
           host.types[Array]
         end
       end
@@ -152,12 +163,12 @@ module Oso
         host.make_instance(cls_name, args: args, kwargs: kwargs, id: id)
       end
 
-      # Create a generator that can be polled to advance the query loop.
+      # Run the main Polar loop, yielding results as they are emitted from the VM.
       #
       # @yieldparam [Hash<String, Object>]
       # @return [Enumerator]
       # @raise [Error] if any of the FFI calls raise one.
-      def each # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def run # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         loop do # rubocop:disable Metrics/BlockLength
           event = ffi_query.next_event
           case event.kind
@@ -227,21 +238,21 @@ module Oso
         return unless typ
 
         rel = typ.fields[attr]
-        return unless rel.is_a? ::Oso::Polar::DataFiltering::Relationship
+        return unless rel.is_a? ::Oso::Polar::DataFiltering::Relation
 
         rel
       end
 
       def handle_relationship(call_id, instance, rel) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        fetcher = host.types[rel.other_type].fetcher
-        constraint = ::Oso::Polar::DataFiltering::Constraint.new(
+        typ = host.types[rel.other_type]
+        constraint = ::Oso::Polar::DataFiltering::Filter.new(
           kind: 'Eq',
           field: rel.other_field,
           value: instance.send(rel.my_field)
         )
-        res = fetcher[[constraint]].uniq
+        res = typ.exec_query[typ.build_query[[constraint]]]
 
-        if rel.kind == 'parent'
+        if rel.kind == 'one'
           raise "multiple parents: #{res}" unless res.length == 1
 
           res = res[0]

data/lib/oso/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Oso
-  VERSION = '0.20.0-beta'
+  VERSION = '0.20.1-beta'
 end

data/lib/oso.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 require 'oso/oso'
+require 'oso/errors'
 require 'oso/polar'
 require 'oso/version'
 
-# Top-level namespace for oso authorization library.
+# Top-level namespace for Oso authorization library.
 module Oso
-  def self.new
-    ::Oso::Oso.new
+  def self.new(not_found_error: NotFoundError, forbidden_error: ForbiddenError, read_action: 'read')
+    ::Oso::Oso.new(not_found_error: not_found_error, forbidden_error: forbidden_error, read_action: read_action)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oso-oso
 version: !ruby/object:Gem::Version
-  version: 0.20.0.pre.beta
+  version: 0.20.1.pre.beta
 platform: ruby
 authors:
 - Oso Security, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-24 00:00:00.000000000 Z
+date: 2021-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -158,6 +158,7 @@ files:
 - ext/oso-oso/lib/libpolar.so
 - ext/oso-oso/lib/polar.dll
 - lib/oso.rb
+- lib/oso/errors.rb
 - lib/oso/oso.rb
 - lib/oso/polar.rb
 - lib/oso/polar/data_filtering.rb