cerbos 0.1.0

data/lib/cerbos/input/jwt.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Input
+    # A JSON Web Token to use as an auxiliary data source, which will be verified against the Cerbos policy decision point (PDP) server's configured JSON Web Key Sets (JWKS) unless verification is disabled on the server.
+    #
+    # @see https://docs.cerbos.dev/cerbos/latest/configuration/auxdata.html#_jwt Configuring the PDP
+    class JWT
+      # The encoded JWT.
+      #
+      # @return [String]
+      attr_reader :token
+
+      # The ID of the JWKS to be used by the PDP server to verify the JWT.
+      #
+      # @return [String]
+      # @return [nil] if not provided (in which case the PDP server must have only one JWKS configured or verification disabled).
+      attr_reader :key_set_id
+
+      # Specify a JWT to use as an auxiliary data source.
+      #
+      # @param token [String] the encoded JWT.
+      # @param key_set_id [String, nil] the ID of the JWKS to be used by the PDP server to verify the JWT. May be set to `nil` if the PDP server only has one JWKS configured or verification disabled.
+      def initialize(token:, key_set_id: nil)
+        @token = token
+        @key_set_id = key_set_id
+      end
+
+      # @private
+      def to_protobuf
+        Protobuf::Cerbos::Request::V1::AuxData::JWT.new(
+          token: token,
+          key_set_id: key_set_id
+        )
+      end
+    end
+  end
+end

data/lib/cerbos/input/principal.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Input
+    # A principal (often a user, but potentially another actor like a service account) to authorize.
+    class Principal
+      # A unique identifier for the principal.
+      #
+      # @return [String]
+      attr_reader :id
+
+      # The roles held by the principal.
+      #
+      # @return [Array<String>]
+      attr_reader :roles
+
+      # Application-specific attributes describing the principal.
+      #
+      # @return [Attributes]
+      attr_reader :attributes
+
+      # The policy version to use when authorizing the principal.
+      #
+      # @return [String]
+      # @return [nil] if not provided (in which case the Cerbos policy decision point server's configured default version will be used).
+      attr_reader :policy_version
+
+      # The policy scope to use when authorizing the principal.
+      #
+      # @return [String]
+      # @return [nil] if not provided.
+      #
+      # @see https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html Scoped policies
+      attr_reader :scope
+
+      # Specify a principal to authorize.
+      #
+      # @param id [String] a unique identifier for the principal.
+      # @param roles [Array<String>] the roles held by the principal.
+      # @param attributes [Attributes, Hash] application-specific attributes describing the principal.
+      # @param policy_version [String, nil] the policy version to use when authorizing the principal (`nil` to use the Cerbos policy decision point server's configured default version).
+      # @param scope [String, nil] the policy scope to use when authorizing the principal.
+      def initialize(id:, roles:, attributes: {}, policy_version: nil, scope: nil)
+        @id = id
+        @roles = roles
+        @attributes = Input.coerce_required(attributes, Attributes)
+        @policy_version = policy_version
+        @scope = scope
+      end
+
+      # @private
+      def to_protobuf
+        Protobuf::Cerbos::Engine::V1::Principal.new(
+          id: id,
+          roles: roles,
+          attr: attributes.to_protobuf,
+          policy_version: policy_version,
+          scope: scope
+        )
+      end
+    end
+  end
+end

data/lib/cerbos/input/resource.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Input
+    # A resource on which to check a principal's permissions.
+    class Resource
+      # The type of resource.
+      #
+      # @return [String]
+      attr_reader :kind
+
+      # A unique identifier for the resource.
+      #
+      # @return [String]
+      attr_reader :id
+
+      # Application-specific attributes describing the resource.
+      #
+      # @return [Attributes]
+      attr_reader :attributes
+
+      # The policy version to use when checking the principal's permissions on the resource.
+      #
+      # @return [String]
+      # @return [nil] if not provided (in which case the Cerbos policy decision point server's configured default version will be used).
+      attr_reader :policy_version
+
+      # The policy scope to use when checking the principal's permissions on the resource.
+      #
+      # @return [String]
+      # @return [nil] if not provided.
+      #
+      # @see https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html Scoped policies
+      attr_reader :scope
+
+      # Specify a resource on which to check a principal's permissions.
+      #
+      # @param kind [String] the type of resource.
+      # @param id [String] a unique identifier for the resource.
+      # @param attributes [Attributes, Hash] application-specific attributes describing the resource.
+      # @param policy_version [String, nil] the policy version to use when checking the principal's permissions on the resource (`nil` to use the Cerbos policy decision point server's configured default version).
+      # @param scope [String, nil] the policy scope to use when checking the principal's permissions on the resource.
+      def initialize(kind:, id:, attributes: {}, policy_version: nil, scope: nil)
+        @kind = kind
+        @id = id
+        @attributes = Input.coerce_required(attributes, Attributes)
+        @policy_version = policy_version
+        @scope = scope
+      end
+
+      # @private
+      def to_protobuf
+        Protobuf::Cerbos::Engine::V1::Resource.new(
+          kind: kind,
+          id: id,
+          attr: attributes.to_protobuf,
+          policy_version: policy_version,
+          scope: scope
+        )
+      end
+    end
+  end
+end

data/lib/cerbos/input/resource_check.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Input
+    # A resource and actions to check a principal's permissions.
+    class ResourceCheck
+      # The resource to check.
+      #
+      # @return [Resource]
+      attr_reader :resource
+
+      # The actions to check.
+      #
+      # @return [Array<String>]
+      attr_reader :actions
+
+      # Specify a resource and actions to check a principal's permissions.
+      #
+      # @param resource [Resource, Hash] the resource to check.
+      # @param actions [Array<String>] the actions to check.
+      def initialize(resource:, actions:)
+        @resource = Input.coerce_required(resource, Resource)
+        @actions = actions
+      end
+
+      # @private
+      def to_protobuf
+        Protobuf::Cerbos::Request::V1::CheckResourcesRequest::ResourceEntry.new(
+          resource: resource.to_protobuf,
+          actions: actions
+        )
+      end
+    end
+  end
+end

data/lib/cerbos/input/resource_query.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Input
+    # Partial details of resources to be queried.
+    class ResourceQuery
+      # The type of resources to be queried.
+      #
+      # @return [String]
+      attr_reader :kind
+
+      # Any application-specific attributes describing the resources to be queried that are known in advance.
+      #
+      # @return [Attributes]
+      attr_reader :attributes
+
+      # The policy version to use when planning the query.
+      #
+      # @return [String]
+      # @return [nil] if not provided (in which case the Cerbos policy decision point server's configured default version will be used).
+      attr_reader :policy_version
+
+      # The policy scope to use when planning the query.
+      #
+      # @return [String]
+      # @return [nil] if not provided.
+      #
+      # @see https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html Scoped policies
+      attr_reader :scope
+
+      # Specify partial details of resources to be queried.
+      #
+      # @param kind [String] the type of resources to be queried.
+      # @param attributes [Attributes, Hash] any application-specific attributes describing the resources to be queried that are known in advance.
+      # @param policy_version [String, nil] the policy version to use when planning the query (`nil` to use the Cerbos policy decision point server's configured default version).
+      # @param scope [String, nil] the policy scope to use when planning the query.
+      def initialize(kind:, attributes: {}, policy_version: nil, scope: nil)
+        @kind = kind
+        @attributes = Input.coerce_required(attributes, Attributes)
+        @policy_version = policy_version
+        @scope = scope
+      end
+
+      # @private
+      def to_protobuf
+        Protobuf::Cerbos::Engine::V1::PlanResourcesRequest::Resource.new(
+          kind: kind,
+          attr: attributes.to_protobuf,
+          policy_version: policy_version,
+          scope: scope
+        )
+      end
+    end
+  end
+end

data/lib/cerbos/input.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Cerbos
+  # Namespace for objects passed to {Client} methods.
+  module Input
+    # @private
+    def self.coerce_required(value, to_class)
+      raise ArgumentError, "Value is required" if value.nil?
+      return value if value.is_a?(to_class)
+
+      to_class.new(**value)
+    rescue ArgumentError, TypeError => error
+      raise Error::InvalidArgument.new(details: "Failed to create #{to_class.name} from #{value.inspect}: #{error}")
+    end
+
+    # @private
+    def self.coerce_optional(value, to_class)
+      return nil if value.nil?
+
+      coerce_required(value, to_class)
+    end
+
+    # @private
+    def self.coerce_array(values, to_class)
+      values.map { |value| coerce_required(value, to_class) }
+    end
+  end
+end
+
+require_relative "input/attributes"
+require_relative "input/aux_data"
+require_relative "input/jwt"
+require_relative "input/principal"
+require_relative "input/resource"
+require_relative "input/resource_check"
+require_relative "input/resource_query"

data/lib/cerbos/mutual_tls.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cerbos
+  # Settings for encrypting the gRPC connection and authenticating the client with mutual TLS.
+  class MutualTLS < TLS
+    # The PEM-encoded client certificate.
+    #
+    # @return [String]
+    attr_reader :client_certificate_pem
+
+    # The PEM-encoded client private key.
+    #
+    # @return [String]
+    attr_reader :client_key_pem
+
+    # Create settings for encrypting the gRPC connection and authenticating the client with mutual TLS.
+    #
+    # @param client_certificate_pem [String] the PEM-encoded client certificate.
+    # @param client_key_pem [String] the PEM-encoded client private key.
+    # @param tls_settings [Hash] arguments to pass to {TLS#initialize}.
+    def initialize(client_certificate_pem:, client_key_pem:, **tls_settings)
+      super(**tls_settings)
+
+      @client_certificate_pem = client_certificate_pem
+      @client_key_pem = client_key_pem
+    end
+
+    # @private
+    def to_channel_credentials
+      GRPC::Core::ChannelCredentials.new(root_certificates_pem, client_key_pem, client_certificate_pem)
+    end
+  end
+end

data/lib/cerbos/output/check_resources.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Output
+    # The outcome of checking a principal's permissions on a set of resources.
+    #
+    # @see Client#check_resources
+    CheckResources = Output.new_class(:request_id, :results) do
+      # @!attribute [r] request_id
+      #   The identifier for tracing the request.
+      #
+      #   @return [String]
+
+      # @!attribute [r] results
+      #   The outcomes of the permission checks for each resource.
+      #
+      #   @return [Array<Result>]
+
+      def self.from_protobuf(check_resources)
+        new(
+          request_id: check_resources.request_id,
+          results: (check_resources.results || []).map { |entry| CheckResources::Result.from_protobuf(entry) }
+        )
+      end
+
+      # Check the policy decision was that an action should be allowed for a resource.
+      #
+      # @param resource [Input::Resource, Hash] the resource search criteria (see {#find_result}).
+      # @param action [String] the action to check.
+      #
+      # @return [Boolean]
+      # @return [nil] if the resource or action is not present in the results.
+      def allow?(resource:, action:)
+        find_result(resource)&.allow?(action)
+      end
+
+      # Find an item from {#results} by resource.
+      #
+      # @param resource [Input::Resource, Hash] the resource search criteria. `kind` and `id` are required; `policy_version` and `scope` may also be provided if needed to distinguish between multiple results for the same `kind` and `id`.
+      #
+      # @return [Result]
+      # @return [nil] if not found.
+      def find_result(resource)
+        search = Input.coerce_required(resource, Input::Resource)
+        results.find { |result| matching_resource?(search, result.resource) }
+      end
+
+      private
+
+      def matching_resource?(search, candidate)
+        search.kind == candidate.kind &&
+          search.id == candidate.id &&
+          (search.policy_version.nil? || search.policy_version == candidate.policy_version) &&
+          (search.scope.nil? || search.scope == candidate.scope)
+      end
+    end
+
+    # The outcome of checking a principal's permissions on single resource.
+    CheckResources::Result = Output.new_class(:resource, :actions, :validation_errors, :metadata) do
+      # @!attribute [r] resource
+      #   The resource that was checked.
+      #
+      #   @return [Resource]
+
+      # @!attribute [r] actions
+      #   The policy decisions for each action.
+      #
+      #   @return [Hash{String => :EFFECT_ALLOW, :EFFECT_DENY}]
+
+      # @!attribute [r] validation_errors
+      #   Any schema validation errors for the principal or resource attributes.
+      #
+      #   @return [Array<ValidationError>]
+
+      # @!attribute [r] metadata
+      #   Additional information about how the policy decisions were reached.
+      #
+      #   @return [Metadata]
+      #   @return [nil] if `include_metadata` was `false`.
+
+      def self.from_protobuf(entry)
+        new(
+          resource: CheckResources::Result::Resource.from_protobuf(entry.resource),
+          actions: entry.actions.to_h,
+          validation_errors: (entry.validation_errors || []).map { |validation_error| CheckResources::Result::ValidationError.from_protobuf(validation_error) },
+          metadata: CheckResources::Result::Metadata.from_protobuf(entry.meta)
+        )
+      end
+
+      # Check if the policy decision was that a given action should be allowed for the resource.
+      #
+      # @return [Boolean]
+      # @return [nil] if the action is not present in the results.
+      def allow?(action)
+        actions[action]&.eql?(:EFFECT_ALLOW)
+      end
+
+      # List the actions that should be allowed for the resource.
+      #
+      # @return [Array<String>]
+      def allowed_actions
+        actions.filter_map { |action, effect| action if effect == :EFFECT_ALLOW }
+      end
+    end
+
+    # A resource that was checked.
+    CheckResources::Result::Resource = Output.new_class(:kind, :id, :policy_version, :scope) do
+      # @!attribute [r] kind
+      #   The type of resource.
+      #
+      #   @return [String]
+
+      # @!attribute [r] id
+      #   The unique identifier of the resource.
+      #
+      #   @return [String]
+
+      # @!attribute [r] policy_version
+      #   The policy version against which the check was performed.
+      #
+      #   @return [String]
+
+      # @!attribute [r] scope
+      #   The policy scope against which the check was performed.
+      #
+      #   @return [String]
+      #
+      #   @see https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html Scoped policies
+
+      def self.from_protobuf(resource)
+        new(
+          kind: resource.kind,
+          id: resource.id,
+          policy_version: resource.policy_version,
+          scope: resource.scope
+        )
+      end
+    end
+
+    # An error that occurred while validating the principal or resource attributes against a schema.
+    CheckResources::Result::ValidationError = Output.new_class(:path, :message, :source) do
+      # @!attribute [r] path
+      #   The path to the attribute that failed validation.
+      #
+      #   @return [String]
+
+      # @!attribute [r] message
+      #   The error message.
+      #
+      #   @return [String]
+
+      # @!attribute [r] source
+      #   The source of the invalid attributes.
+      #
+      #   @return [:SOURCE_PRINCIPAL, :SOURCE_RESOURCE]
+
+      def self.from_protobuf(validation_error)
+        new(
+          path: validation_error.path,
+          message: validation_error.message,
+          source: validation_error.source
+        )
+      end
+
+      # Check if the principal's attributes failed schema validation.
+      #
+      # @return [Boolean]
+      def from_principal?
+        source == :SOURCE_PRINCIPAL
+      end
+
+      # Check if the resource's attributes failed schema validation.
+      #
+      # @return [Boolean]
+      def from_resource?
+        source == :SOURCE_RESOURCE
+      end
+    end
+
+    # Additional information about how policy decisions were reached.
+    CheckResources::Result::Metadata = Output.new_class(:actions, :effective_derived_roles) do
+      # @!attribute [r] actions
+      #   Additional information about how the policy decision was reached for each action.
+      #
+      #   @return [Hash{String => Effect}]
+
+      # @!attribute [r] effective_derived_roles
+      #   The derived roles that were applied to the principal for the resource.
+      #
+      #   @return [Array<String>]
+      #
+      #   @see https://docs.cerbos.dev/cerbos/latest/policies/derived_roles.html Derived roles
+
+      def self.from_protobuf(meta)
+        return nil if meta.nil?
+
+        new(
+          actions: meta.actions.map { |action, effect| [action, CheckResources::Result::Metadata::Effect.from_protobuf(effect)] }.to_h,
+          effective_derived_roles: meta.effective_derived_roles || []
+        )
+      end
+    end
+
+    # Additional information about how a policy decision was reached.
+    CheckResources::Result::Metadata::Effect = Output.new_class(:matched_policy, :matched_scope) do
+      # @!attribute [r] matched_policy
+      #   The policy that was used to make the decision.
+      #
+      #   @return [String]
+
+      # @!attribute [r] matched_scope
+      #   The policy scope that was used to make the decision.
+      #
+      #   @return [String]
+      #
+      #   @see https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html Scoped policies
+
+      def self.from_protobuf(effect_meta)
+        new(
+          matched_policy: effect_meta.matched_policy,
+          matched_scope: effect_meta.matched_scope
+        )
+      end
+    end
+  end
+end

data/lib/cerbos/output/plan_resources.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Cerbos
+  module Output
+    # A query plan that can be used to obtain a list of resources on which a principal is allowed to perform a particular action.
+    #
+    # @see Client#plan_resources
+    PlanResources = Output.new_class(:request_id, :kind, :condition, :metadata) do
+      # @!attribute [r] request_id
+      #   The identifier for tracing the request.
+      #
+      #   @return [String]
+
+      # @!attribute [r] kind
+      #   The type of plan.
+      #
+      #   @return [:KIND_ALWAYS_ALLOWED, :KIND_ALWAYS_DENIED, :KIND_CONDITIONAL]
+
+      # @!attribute [r] condition
+      #   The root node of the query condition abstract syntax tree.
+      #
+      #   @return [Expression, Expression::Variable]
+      #   @return [nil] if the specified action is not conditional (is always allowed or denied) for the principal on resources matching the input.
+      #
+      #   @see #always_allowed?
+      #   @see #always_denied?
+      #   @see #conditional?
+
+      # @!attribute [r] metadata
+      #   Additional information about the query plan.
+      #
+      #   @return [Metadata]
+      #   @return [nil] if `include_metadata` was `false`.
+
+      def self.from_protobuf(plan_resources)
+        new(
+          request_id: plan_resources.request_id,
+          kind: plan_resources.filter.kind,
+          condition: PlanResources::Expression::Operand.from_protobuf(plan_resources.filter.condition),
+          metadata: PlanResources::Metadata.from_protobuf(plan_resources.meta)
+        )
+      end
+
+      # Check if the specified action is always allowed for the principal on resources matching the input.
+      #
+      # @return [Boolean]
+      def always_allowed?
+        kind == :KIND_ALWAYS_ALLOWED
+      end
+
+      # Check if the specified action is always denied for the principal on resources matching the input.
+      #
+      # @return [Boolean]
+      def always_denied?
+        kind == :KIND_ALWAYS_DENIED
+      end
+
+      # Check if the specified action is conditionally allowed for the principal on resources matching the input.
+      #
+      # @return [Boolean]
+      def conditional?
+        kind == :KIND_CONDITIONAL
+      end
+    end
+
+    # An abstract syntax tree node representing an expression to evaluate.
+    PlanResources::Expression = Output.new_class(:operator, :operands) do
+      # @!attribute [r] operator
+      #   The operator to invoke.
+      #
+      #   @return [String]
+
+      # @!attribute [r] operands
+      #   The operands on which to invoke the operator.
+      #
+      #   @return [Array<Expression, Value, Variable>]
+
+      def self.from_protobuf(expression)
+        new(
+          operator: expression.operator,
+          operands: (expression.operands || []).map { |operand| PlanResources::Expression::Operand.from_protobuf(operand) }
+        )
+      end
+    end
+
+    # @private
+    module PlanResources::Expression::Operand
+      def self.from_protobuf(operand)
+        if operand.nil?
+          nil
+        elsif operand.has_expression?
+          PlanResources::Expression.from_protobuf(operand.expression)
+        elsif operand.has_value?
+          PlanResources::Expression::Value.from_protobuf(operand.value)
+        else
+          PlanResources::Expression::Variable.from_protobuf(operand.variable)
+        end
+      end
+    end
+
+    # An abstract syntax tree node representing a constant value.
+    PlanResources::Expression::Value = Output.new_class(:value) do
+      # @!attribute [r] value
+      #   The constant value.
+      #
+      #   @return [String, Numeric, Boolean, Array, Hash, nil]
+
+      def self.from_protobuf(value)
+        new(value: value.to_ruby(true))
+      end
+    end
+
+    # An abstract syntax tree node representing a variable whose value was unknown when producing the query plan.
+    PlanResources::Expression::Variable = Output.new_class(:name) do
+      # @!attribute [r] name
+      #   The name of the variable.
+      #
+      #   @return [String]
+
+      def self.from_protobuf(variable)
+        new(name: variable)
+      end
+    end
+
+    # Additional information about the query plan.
+    PlanResources::Metadata = Output.new_class(:condition_string, :matched_scope) do
+      # @!attribute [r] condition_string
+      #   The query condition abstract syntax tree rendered as a human-readable string, to help with debugging.
+      #
+      #   @return [String]
+
+      # @!attribute [r] matched_scope
+      #   The policy scope that was used to plan the query.
+      #
+      #   @return [String]
+      #
+      #   @see https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html Scoped policies
+
+      def self.from_protobuf(meta)
+        return nil if meta.nil?
+
+        new(
+          condition_string: meta.filter_debug,
+          matched_scope: meta.matched_scope
+        )
+      end
+    end
+  end
+end