oso-cloud 1.9.1 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 971ae28cc897b2bb71f88e0129fedb100bccc8edf285b49c7c62b045bdf360cc
-  data.tar.gz: 75e108ed7c4090b207ff9f2860d67c80e5b2e0e257ba4e6ee12f7b89148228f6
+  metadata.gz: 6dac67a8075972556f7ae65a0536ec256633cb2262e09bc846c0d9abd5d076b7
+  data.tar.gz: 5f99588ce46c6aa63eec48ba8c157f493a86f6341f7c3983ebaaef82712d424d
 SHA512:
-  metadata.gz: ad4bcfe3809d95409113caf477b43fdf3dd18b24a8d4d5fc2479cdae0207fc187a16121406bc63a573c8c160d41e4a37e8aa56f761a0cd8195552238df68882e
-  data.tar.gz: e7dc543034f9175b7a533569e780166caf07fa836a614881a482e295d66cfdce82e691a5c46a4b23603e25c256458c5dc50fb1f4eb305649fdadc2e610a7a6e3
+  metadata.gz: e208dbfa5c8d680d6887369deb5acaf157ab3d06ed408b9fa375823a00c39a9c7a2bf397d1fb14d0716d71b9518bd1f7124900d7dc0ae586a2b12f964ff23315
+  data.tar.gz: c4485eaf638f9e262c8b035c5b6606b0162fea19babe548f1ffd14cbee977e1ee0408f3679bc2f87eb984debeef86f176c4e0dcbed5c3164dea3acd7066fc515

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    oso-cloud (1.9.1)
+    oso-cloud (1.10.0)
       faraday (~> 2.5.2)
       faraday-net_http_persistent (~> 2.0)
       faraday-retry (~> 2.0.0)

data/lib/oso/api.rb

@@ -403,9 +403,9 @@ module OsoCloud
         ApiResult.new(**result)
       end
 
-      def post_authorize(data)
+      def post_authorize(data, parity_handle = nil)
         url = '/authorize'
-        result = POST(url, nil, data, false)
+        result = POST(url, nil, data, false, parity_handle: parity_handle)
         AuthorizeResult.new(**result)
       end
 
@@ -445,10 +445,10 @@ module OsoCloud
         StatsResult.new(**result)
       end
 
-      def post_authorize_query(query)
+      def post_authorize_query(query, parity_handle = nil)
         url = '/authorize_query'
         data = LocalAuthQuery.new(query: query, data_bindings: @data_bindings)
-        result = POST(url, nil, data, false)
+        result = POST(url, nil, data, false, parity_handle: parity_handle)
         LocalQueryResult.new(**result)
       end
 
@@ -532,7 +532,7 @@ module OsoCloud
         handle_faraday_error e
       end
 
-      def POST(path, params, body, isMutation)
+      def POST(path, params, body, isMutation, parity_handle: nil)
         max_body_size = 10 * 1024 * 1024
         hash = OsoCloud::Helpers.to_hash(body) unless body.nil?
         json_str = JSON.generate(hash)
@@ -550,6 +550,12 @@ module OsoCloud
 
           create_api_error(response, "Unexpected status #{response.status}") if response.status >= 300 || response.status < 200
 
+          if parity_handle && response.headers['X-Request-ID']
+            parity_handle.set(response.headers['X-Request-ID'], self)
+          elsif parity_handle && !response.headers['X-Request-ID']
+            raise ApiError.new(message: "unable to use Parity Handle: no request ID returned from Oso")
+          end
+
           @last_offset = response.headers[:OsoOffset] if isMutation
           response.body
         # only attempt fallback on 5xx, and connection failure conditions
@@ -609,6 +615,16 @@ module OsoCloud
               end
         raise ApiError.new(message: err + formatted_request_id)
       end
+
+      def post_expected_result(expected_result)
+        url = '/expect'
+        unless expected_result.is_a?(OsoCloud::Core::ExpectedResult)
+          raise ArgumentError, "Expected parameter to be an ExpectedResult object, got #{expected_result.class}"
+        end
+
+        result = POST(url, nil, expected_result, false)
+        ApiResult.new(**result)
+      end
     end
   end
 end

data/lib/oso/oso.rb

@@ -38,12 +38,19 @@ module OsoCloud
     #
     # Returns a SQL query to run against the local database
     #
+    # This method has an optional parameter `parity_handle` which is used to compare
+    # the result of your Oso authorization check with your legacy authorization system.
+    # Learn more about using the parity_handle with Oso Migrate here:
+    #
+    # https://www.osohq.com/docs/app-integration/client-apis/ruby#oso-migrate
+    #
     # @param actor [OsoCloud::Value]
     # @param action [String]
     # @param resource [OsoCloud::Value]
     # @param context_facts [Array<fact>]
+    # @param parity_handle [OsoCloud::ParityHandle, nil] Optional handle for parity checks with Oso Migrate.
     # @return [String]
-    def authorize_local(actor, action, resource, context_facts = [])
+    def authorize_local(actor, action, resource, context_facts = [], parity_handle: nil)
       actor_typed_id = actor.to_api_value
       resource_typed_id = resource.to_api_value
       result = @api.post_authorize_query(
@@ -54,7 +61,7 @@ module OsoCloud
           resource_type: resource_typed_id.type,
           resource_id: resource_typed_id.id,
           context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
-        )
+        ), parity_handle
       )
       result.sql
     end
@@ -134,13 +141,20 @@ module OsoCloud
     # Returns true if the actor can perform the action on the resource;
     # otherwise false.
     #
+    # This method has an optional parameter `parity_handle` which is used to compare
+    # the result of your Oso authorization check with your legacy authorization system.
+    # Learn more about using the parity_handle with Oso Migrate here:
+    #
+    # https://www.osohq.com/docs/app-integration/client-apis/ruby#oso-migrate
+    #
     # @param actor [OsoCloud::Value]
     # @param action [String]
     # @param resource [OsoCloud::Value]
     # @param context_facts [Array<fact>]
+    # @param parity_handle [OsoCloud::ParityHandle, nil] Optional handle for parity checks with Oso Migrate.
     # @return [Boolean]
     # @see Oso for more information about facts
-    def authorize(actor, action, resource, context_facts = [])
+    def authorize(actor, action, resource, context_facts = [], parity_handle: nil)
       actor_typed_id = actor.to_api_value
       resource_typed_id = resource.to_api_value
       result = @api.post_authorize(OsoCloud::Core::AuthorizeQuery.new(
@@ -150,7 +164,9 @@ module OsoCloud
                                      resource_type: resource_typed_id.type,
                                      resource_id: resource_typed_id.id,
                                      context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
-                                   ))
+                                   ),
+                                   parity_handle
+                                   )
       result.allowed
     end
 

data/lib/oso/parity_handle.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'oso/api'
+
+module OsoCloud
+  # @!visibility private
+  module Core
+    # @!visibility private
+    class ExpectedResult
+      attr_reader :request_id, :expected
+
+      def initialize(request_id:, expected:)
+        @request_id = request_id
+        @expected = expected
+      end
+    end
+  end
+
+  # ParityHandle is a testing utility in Oso Migrate for comparing expected authorization
+  # decisions with actual Oso results.
+  class ParityHandle
+    attr_reader :request_id, :expected
+
+    def initialize
+      @api = nil
+      @request_id = nil
+      @expected = nil
+    end
+
+    # Set is an internal method called by the API class after authorize.
+    #
+    # @param request_id [String] The ID of the authorization request.
+    # @param api [OsoCloud::Core::Api] Reference to the API instance.
+    # @return [nil]
+    # @raise [StandardError] If request_id is set twice.
+    # @!visibility private
+    def set(request_id, api)
+      unless @request_id.nil?
+        raise StandardError,
+              "attempted to set request_id twice. Only one request is allowed per ParityHandle instance. (Original request ID: #{@request_id})"
+      end
+
+      @request_id = request_id
+      @api = api
+
+      send_expected_result unless @expected.nil?
+      nil
+    end
+
+    # Expect is a public method for users to indicate the expected result of an authorization query.
+    #
+    # @param expected [Boolean] Boolean indicating the expected authorization result.
+    # @return [nil]
+    # @raise [StandardError] If expected result is set twice.
+    def expect(expected)
+      raise StandardError, 'attempted to set expected result twice' unless @expected.nil?
+
+      @expected = expected
+
+      send_expected_result unless @request_id.nil?
+      nil
+    end
+
+    private
+
+    # Send the expected result to the API
+    # @!visibility private
+    def send_expected_result
+      raise StandardError, 'ParityHandle not properly initialized' if @api.nil? || @request_id.nil? || @expected.nil?
+
+      expected_result = OsoCloud::Core::ExpectedResult.new(
+        request_id: @request_id,
+        expected: @expected
+      )
+
+      @api.post_expected_result(expected_result)
+    end
+  end
+end

data/lib/oso/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# !! IMPORTANT: Update the ruby docs to reflect the latest version !!
 module OsoCloud
-  VERSION = '1.9.1'.freeze
+  VERSION = '1.10.0'
 end

data/lib/oso-cloud.rb

@@ -1 +1,2 @@
 require 'oso/oso'
+require 'oso/parity_handle'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oso-cloud
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.10.0
 platform: ruby
 authors:
 - Oso Security, Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -113,6 +113,7 @@ files:
 - lib/oso/api.rb
 - lib/oso/helpers.rb
 - lib/oso/oso.rb
+- lib/oso/parity_handle.rb
 - lib/oso/version.rb
 - oso-cloud.gemspec
 homepage: https://www.osohq.com/