gitlab-glaz 2.0.0-x86_64-linux-gnu → 2.2.0-x86_64-linux-gnu

data/lib/gitlab/glaz/govern_policy_engine.rb

@@ -9,20 +9,22 @@ module Gitlab
     # policy evaluator.
     #
     # Evaluation is trigger-keyed: the caller supplies an event trigger and
-    # the context document, and the engine fetches the applicable policies
-    # from the Policy Store REST API named at construction. Authentication
-    # is per request (+store_authorization+ on #evaluate), never per engine
-    # and never from the environment. The engine executes no actions; the
-    # caller does.
+    # the context document. The policies come either with the call
+    # (+policies:+ on #evaluate, for a caller that already has them, such as
+    # the Policy Store itself) or from the Policy Store REST API named at
+    # construction. Authentication for the REST API is per request
+    # (+store_authorization+ on #evaluate), never per engine and never from
+    # the environment. The engine executes no actions; the caller does.
     #
     # #validate and #debug_evaluate never touch the store, so an engine
-    # built without one (the Policy Store itself) still serves them and
-    # fails #evaluate closed with an ArgumentError.
+    # built without one still serves them, and serves #evaluate when
+    # +policies:+ is given. An #evaluate call without +policies:+ on such an
+    # engine fails closed with an ArgumentError.
     #
-    # #evaluate releases the GVL around the store lookup. It cannot be
-    # interrupted from Ruby until it returns, which is bounded by the
-    # lookup timeouts plus the batch evaluation. Instances are safe to
-    # share across threads and across a fork.
+    # #evaluate releases the GVL around the native call. It cannot be
+    # interrupted from Ruby until it returns, which is bounded by the lookup
+    # timeouts plus the batch evaluation. Instances are safe to share across
+    # threads and across a fork.
     class GovernPolicyEngine
       # Argument checks, raising ArgumentError instead of letting a
       # Google::Protobuf::TypeError or JSON error escape from the wire layer.
@@ -81,6 +83,138 @@ module Gitlab
           string.nil? || string.empty? ? nil : string
         end
 
+        MODES = {
+          "enforce" => :GOVERN_ENFORCEMENT_MODE_ENFORCE,
+          "audit" => :GOVERN_ENFORCEMENT_MODE_AUDIT,
+          "warn" => :GOVERN_ENFORCEMENT_MODE_WARN
+        }.freeze
+        private_constant :MODES
+
+        # Builds the wire set from policy Hashes shaped like the Policy
+        # Store's policy entity. String or Symbol keys; keys the engine does
+        # not read, such as +lifecycle_state+, are ignored. Only the shape is
+        # checked here. Whether each policy belongs to the request's trigger
+        # and organization is the engine's check.
+        def policies!(policies)
+          return nil if policies.nil?
+          raise ArgumentError, "policies must be nil or an Array; got #{policies.class}" unless policies.is_a?(Array)
+
+          ::Gitlab::Glaz::Govern::V1::GovernPolicySet.new(
+            policies: policies.each_with_index.map { |policy, index| policy!(policy, "policies[#{index}]") }
+          )
+        end
+
+        def policy!(policy, name)
+          raise ArgumentError, "#{name} must be a Hash; got #{policy.class}" unless policy.is_a?(Hash)
+
+          policy = policy.transform_keys(&:to_s)
+          # Name the policy by id as well, as the native layer's errors do.
+          name = "#{name} (id #{policy['id']})" if policy["id"].is_a?(Integer)
+          dimensions, namespace_id = policy.values_at("scope_dimensions", "namespace_id")
+
+          attributes = {
+            id: integer!(policy["id"], "#{name}.id"),
+            name: optional_string!(policy["name"], "#{name}.name"),
+            trigger: string!(policy["trigger_type"], "#{name}.trigger_type"),
+            organization_id: integer!(policy["organization_id"], "#{name}.organization_id"),
+            mode: mode!(policy["mode"], "#{name}.mode"),
+            scope_rego: optional_string!(policy["scope_rego"], "#{name}.scope_rego"),
+            scope_dimensions: dimensions.nil? ? nil : scope_dimensions!(dimensions, "#{name}.scope_dimensions"),
+            policy_rego: string!(policy["policy_rego"], "#{name}.policy_rego"),
+            actions: actions!(policy["actions"], "#{name}.actions"),
+            violation_details: violation_details!(policy["violation_details"], "#{name}.violation_details")
+          }
+          # The owner is explicit on the wire: nil is an organization-level
+          # policy, never an unset field, so a missing key is an error rather
+          # than a silent default.
+          unless policy.key?("namespace_id")
+            raise ArgumentError, "#{name}.namespace_id must be present (nil for an organization-level policy)"
+          end
+
+          if namespace_id.nil?
+            attributes[:organization_level] = true
+          else
+            attributes[:namespace_id] = integer!(namespace_id, "#{name}.namespace_id")
+          end
+
+          ::Gitlab::Glaz::Govern::V1::GovernPolicy.new(attributes)
+        end
+
+        def integer!(value, name)
+          unless value.is_a?(Integer) && !value.negative? && value.bit_length <= 64
+            raise ArgumentError, "#{name} must be a non-negative Integer of at most 64 bits; got #{value.inspect}"
+          end
+
+          value
+        end
+
+        def optional_string!(value, name)
+          value.nil? ? "" : string!(value, name)
+        end
+
+        def mode!(value, name)
+          MODES.fetch(value.to_s) do
+            raise ArgumentError, "#{name} must be one of #{MODES.keys.join(', ')}; got #{value.inspect}"
+          end
+        end
+
+        # The engine stamps a mode on every decision, so an unspecified or
+        # unknown one is an engine fault, not a caller mistake.
+        def mode_name(value)
+          MODES.key(value) || raise("decision carries no enforcement mode; got #{value.inspect}")
+        end
+
+        def scope_dimensions!(value, name)
+          unless value.is_a?(Array) && value.all?(String)
+            raise ArgumentError, "#{name} must be nil or an Array of Strings; got #{value.inspect}"
+          end
+
+          ::Gitlab::Glaz::Govern::V1::GovernScopeDimensions.new(paths: value)
+        end
+
+        # The store entity's saved constraints, forwarded onto the policy's
+        # decision as the store lookup forwards them: nil means none, a nil
+        # or missing +expected+ names no value, and other keys are ignored.
+        # The engine checks each path's segments.
+        def violation_details!(value, name)
+          return [] if value.nil?
+          raise ArgumentError, "#{name} must be nil or an Array; got #{value.class}" unless value.is_a?(Array)
+
+          value.each_with_index.map { |detail, index| violation_detail!(detail, "#{name}[#{index}]") }
+        end
+
+        def violation_detail!(detail, name)
+          raise ArgumentError, "#{name} must be a Hash; got #{detail.class}" unless detail.is_a?(Hash)
+
+          detail = detail.transform_keys(&:to_s)
+          expected = detail["expected"]
+          ::Gitlab::Glaz::Govern::V1::GovernViolationDetail.new(
+            path: string!(detail["path"], "#{name}.path"),
+            expected_json: expected.nil? ? "" : JSON.generate(expected)
+          )
+        rescue JSON::JSONError => e
+          raise ArgumentError, "#{name}.expected must serialize to JSON; #{e.message}"
+        end
+
+        def actions!(value, name)
+          return [] if value.nil?
+          raise ArgumentError, "#{name} must be nil or an Array; got #{value.class}" unless value.is_a?(Array)
+
+          value.each_with_index.map { |action, index| action!(action, "#{name}[#{index}]") }
+        end
+
+        def action!(action, name)
+          raise ArgumentError, "#{name} must be a Hash; got #{action.class}" unless action.is_a?(Hash)
+
+          action = action.transform_keys(&:to_s)
+          value = action["value"]
+
+          ::Gitlab::Glaz::Govern::V1::GovernPolicyAction.new(
+            action_type: string!(action["type"], "#{name}.type"),
+            value_json: value.nil? ? "" : json!(value, "#{name}.value")
+          )
+        end
+
         def valid_store_base_url?(parsed_uri)
           parsed_uri.is_a?(URI::HTTP) && !parsed_uri.host.to_s.empty? &&
             parsed_uri.userinfo.nil? && parsed_uri.query.nil? && parsed_uri.fragment.nil? &&
@@ -172,24 +306,46 @@ module Gitlab
       # @param store_authorization [String, nil] the `Authorization` header
       #   value the lookup presents to the Policy Store, verbatim (target
       #   scheme `"Bearer <jwt>"`). nil sends no header. Never logged or
-      #   echoed in errors.
+      #   echoed in errors. Ignored when +policies+ is given.
+      # @param policies [Array<Hash>, nil] the policies to evaluate, for a
+      #   caller that already has them. When given, the engine evaluates
+      #   exactly these and never contacts the store; an empty Array is a
+      #   successful, empty evaluation. nil fetches them from the store.
+      #   Pass the active policies of +trigger+ in the context's
+      #   organization, each shaped like the Policy Store's policy entity
+      #   (String or Symbol keys): `id`, `name`, `trigger_type`,
+      #   `organization_id`, `namespace_id` (required; nil for an
+      #   organization-level policy), `mode` (`"enforce"`, `"audit"` or
+      #   `"warn"`), `scope_rego` (nil or empty when unscoped),
+      #   `scope_dimensions` (Array<String>, or nil when unknown),
+      #   `policy_rego`, `actions` (`{ type:, value: }` entries) and
+      #   `violation_details` (nil, or `{ path:, expected: }` entries: the
+      #   constraints the store saved from {#validate}, forwarded onto the
+      #   policy's decision; `path` is a String and `expected`, nil when the
+      #   policy names no compliant value, must serialize to JSON). Other
+      #   keys are ignored.
       # @raise [ArgumentError] for a caller fault: wrong argument types, a
       #   document that does not serialize to JSON, a blank trigger, a blank
       #   +principal+ or +resource+ (or one exceeding 64 KiB or carrying a
       #   newline), missing organization scope, an oversized input document,
-      #   or an engine constructed without a store.
+      #   a policy in +policies+ that is malformed or belongs to another
+      #   trigger, organization or namespace, more than the per-trigger cap
+      #   of them, or an engine without a store called without +policies+.
       # @raise [RuntimeError] for a backend fault: the store lookup failed
       #   or was rejected, or resolved more policies than the per-trigger
       #   cap. Never an empty batch, which would read as "nothing to
-      #   enforce".
+      #   enforce". Also when the engine stamps the response dry_run.
       # @return [Hash] `{ decisions: Array<Hash>, undecided_policy_ids:
-      #   Array<Integer>, identifier: String }`. +decisions+ has one entry
+      #   Array<Integer>, identifier: String,
+      #   dry_run: Boolean }`. +decisions+ has one entry
       #   per resolved, in-scope policy, in lookup order; empty means
       #   nothing applies. Each decision is `{ policy_id: Integer, matched:
       #   Boolean, actions: Array<Hash>, reasons: Array<Hash>, error: String
-      #   | nil }`; each action `{ action_type: String, message: String |
-      #   nil, params: Hash, gating: Boolean }`; each reason `{ message:
-      #   String | nil, details: Hash }`. +actions+ are exactly those the
+      #   | nil, name: String, mode: String, violation_details: Array<Hash> }`; each violation
+      #   detail is `{ path: String, expected: Object }`, with +expected+ absent when the
+      #   policy names no compliant value; each
+      #   action `{ action_type: String, message: String | nil, params: Hash, gating: Boolean }`; each
+      #   reason `{ message: String | nil, details: Hash }`. +actions+ are exactly those the
       #   store configured on the policy, emitted when it matched. A non-nil
       #   +error+ means the policy could not be decided (broken, or over the
       #   per-evaluation time budget); +matched+ is then false and its id is
@@ -201,34 +357,90 @@ module Gitlab
       #
       #   Verdict: deny when any action is gating or any policy is
       #   undecided, allow otherwise. +matched+ alone decides nothing.
-      def evaluate(trigger:, context:, principal:, resource:, data: nil, store_authorization: nil)
-        if @store_base_url.nil?
-          raise ArgumentError, "this engine has no Policy Store to resolve policies from: pass store_base_url: to " \
-            "Gitlab::Glaz::GovernPolicyEngine.new, or for the shared engine assign " \
-            "Gitlab::Glaz::GovernPolicyEngine.policy_store_url or set GLAZ_POLICY_STORE_URL " \
-            "(e.g. \"https://gitlab.com/api/v4\")"
-        end
+      #   +dry_run+ is always false here; see #evaluate_dry_run to preview.
+      def evaluate(trigger:, context:, principal:, resource:, data: nil, store_authorization: nil, policies: nil)
+        request = evaluation_request(
+          trigger, context, principal, resource, data, store_authorization, policies, dry_run: false
+        )
+
+        response = ::Gitlab::Glaz::Govern::V1::EvaluateGovernPolicyResponse.decode(native.evaluate_policies(request))
+        # A dry-run stamp on an enforcement response would let a host skip
+        # recording a real decision, so treat it as an engine fault.
+        raise "enforcement evaluation response is stamped dry_run" if response.dry_run
+
+        evaluation_result(response)
+      end
+
+      # Preview what #evaluate would decide, without enforcing it. A method
+      # of its own, never a parameter of #evaluate (GOVERN-004): a dry run is
+      # never a gate, so callers must not deny on its result, and nothing
+      # records it. Takes the same arguments, raises the same errors and
+      # returns the same Hash as #evaluate, with +dry_run+ true.
+      #
+      # @raise [RuntimeError] additionally, when the response does not echo
+      #   the dry-run flag, so a dry run can never be mistaken for a verdict.
+      # @return [Hash] see #evaluate.
+      def evaluate_dry_run(
+        trigger:, context:, principal:, resource:, data: nil, store_authorization: nil,
+        policies: nil)
+        request = evaluation_request(
+          trigger, context, principal, resource, data, store_authorization, policies, dry_run: true
+        )
+
+        result = evaluation_result(
+          ::Gitlab::Glaz::Govern::V1::EvaluateGovernPolicyResponse.decode(native.evaluate_policies_dry_run(request))
+        )
+        raise "dry-run evaluation response did not echo dry_run" unless result[:dry_run]
+
+        result
+      end
 
-        encoded = ::Glaz::Govern::V1::EvaluateGovernPolicyRequest.encode(
-          ::Glaz::Govern::V1::EvaluateGovernPolicyRequest.new(
+      # List every policy that could apply to +trigger+ in the context's
+      # organization, each with whether it applies to the context supplied.
+      # A different question from #evaluate ("what must I enforce"): it needs
+      # only the trigger and the lookup keys (`organization.id`, plus the
+      # namespace ids where the trigger needs them), runs no policy's rules
+      # and returns no decisions, so nothing in it can be gated on.
+      #
+      # A policy whose scope reads a context path the caller did not supply
+      # is never evaluated, because a missing path would read as "does not
+      # apply". It comes back as `"might_apply"` with those paths in
+      # +missing_dimensions+: supply them and call again. An explicit nil in
+      # the context counts as absent; an empty Array is a value.
+      #
+      # @param trigger [String] the event, e.g. "deployment_requested".
+      # @param context [Hash] whatever context the caller has (max 1 MiB as
+      #   JSON). Must carry `organization.id`, plus the namespace ids for a
+      #   trigger whose policies belong to namespaces, as on #evaluate.
+      # @param store_authorization [String, nil] as on #evaluate.
+      # @param policies [Array<Hash>, nil] as on #evaluate.
+      # @raise [ArgumentError] for a caller fault, as on #evaluate (there is no
+      #   +principal+ or +resource+ to check).
+      # @raise [RuntimeError] for a backend fault, as on #evaluate, or a row
+      #   whose applicability the engine left unstated without saying why.
+      # @return [Hash] `{ policies: Array<Hash> }`, one entry per resolved
+      #   policy in lookup order, each `{ policy_id: Integer, name: String,
+      #   applicability: "applies" | "not_applicable" | "might_apply" | nil,
+      #   missing_dimensions: Array<String>, error: String | nil }`.
+      #   +missing_dimensions+ is set only with `"might_apply"`, and may be
+      #   empty when the policy's scope paths are unknown. +applicability+
+      #   is nil only alongside an +error+: the policy's scope could not be
+      #   evaluated, so it is neither included nor ruled out. +name+ is for
+      #   display; key on +policy_id+.
+      def list_policies(trigger:, context:, store_authorization: nil, policies: nil)
+        require_policy_source!(policies)
+
+        encoded = ::Gitlab::Glaz::Govern::V1::ListGovernPoliciesRequest.encode(
+          ::Gitlab::Glaz::Govern::V1::ListGovernPoliciesRequest.new(
             trigger: Validation.string!(trigger, "trigger"),
             input_json: Validation.json!(context, "context"),
-            data_json: data.nil? ? "" : Validation.json!(data, "data"),
-            principal: Validation.string!(principal, "principal"),
-            resource: Validation.string!(resource, "resource"),
-            store_authorization: Validation.store_authorization!(store_authorization)
+            store_authorization: Validation.store_authorization!(store_authorization),
+            policies: Validation.policies!(policies)
           )
         )
+        response = ::Gitlab::Glaz::Govern::V1::ListGovernPoliciesResponse.decode(native.list_policies(encoded))
 
-        response = ::Glaz::Govern::V1::EvaluateGovernPolicyResponse.decode(
-          native.evaluate_policies(encoded)
-        )
-
-        {
-          decisions: response.decisions.map { |decision| decision_hash(decision) },
-          undecided_policy_ids: response.undecided_policy_ids.to_a,
-          identifier: response.identifier
-        }
+        { policies: response.policies.map { |row| applicability_hash(row) } }
       end
 
       # Parse and compile a Rego policy without evaluating it. A policy that
@@ -237,24 +449,32 @@ module Gitlab
       # actionable feedback.
       #
       # @param policy_rego [String] Rego source (max 64 KiB).
-      # @raise [ArgumentError] when +policy_rego+ is not a String.
-      # @return [Hash] `{ valid: Boolean, errors: Array<Hash> }`; each error
-      #   is `{ message: String, location: String }` with +location+ in
-      #   `"LINE:COL"` format, or `""` when none is available.
-      def validate(policy_rego:)
-        encoded = ::Glaz::Govern::V1::ValidateGovernPolicyRequest.encode(
-          ::Glaz::Govern::V1::ValidateGovernPolicyRequest.new(
-            policy_rego: Validation.string!(policy_rego, "policy_rego")
+      # @param trigger [String, nil] the trigger the policy is authored for. When
+      #   given and the engine embeds a schema for it, every extracted detail's
+      #   path and expected value are checked against that schema.
+      # @raise [ArgumentError] when +policy_rego+ or a given +trigger+ is not a String.
+      # @return [Hash] `{ valid: Boolean, errors: Array<Hash>,
+      #   violation_details: Array<Hash> }`; each error is `{ message:
+      #   String, location: String }` with +location+ in `"LINE:COL"`
+      #   format, or `""` when none is available. +violation_details+ has
+      #   the shape described on #evaluate and is empty for an invalid
+      #   policy.
+      def validate(policy_rego:, trigger: nil)
+        encoded = ::Gitlab::Glaz::Govern::V1::ValidateGovernPolicyRequest.encode(
+          ::Gitlab::Glaz::Govern::V1::ValidateGovernPolicyRequest.new(
+            policy_rego: Validation.string!(policy_rego, "policy_rego"),
+            trigger: trigger.nil? ? "" : Validation.string!(trigger, "trigger")
           )
         )
 
-        response = ::Glaz::Govern::V1::ValidateGovernPolicyResponse.decode(
+        response = ::Gitlab::Glaz::Govern::V1::ValidateGovernPolicyResponse.decode(
           native.validate(encoded)
         )
 
         {
           valid: response.valid,
-          errors: response.errors.map { |e| { message: e.message, location: e.location } }
+          errors: response.errors.map { |e| { message: e.message, location: e.location } },
+          violation_details: response.violation_details.map { |detail| violation_detail_hash(detail) }
         }
       end
 
@@ -275,8 +495,8 @@ module Gitlab
       #   whatever the query evaluated to (parsed JSON, String keys); nil
       #   when +error+ is set.
       def debug_evaluate(policy_rego:, context:, query:, data: nil)
-        encoded = ::Glaz::Govern::V1::EvaluateGovernPolicyDebugRequest.encode(
-          ::Glaz::Govern::V1::EvaluateGovernPolicyDebugRequest.new(
+        encoded = ::Gitlab::Glaz::Govern::V1::EvaluateGovernPolicyDebugRequest.encode(
+          ::Gitlab::Glaz::Govern::V1::EvaluateGovernPolicyDebugRequest.new(
             policy_rego: Validation.string!(policy_rego, "policy_rego"),
             query: Validation.string!(query, "query"),
             input_json: Validation.json!(context, "context"),
@@ -312,6 +532,41 @@ module Gitlab
         @native
       end
 
+      def require_policy_source!(policies)
+        return unless @store_base_url.nil? && policies.nil?
+
+        raise ArgumentError, "this engine has no Policy Store to resolve policies from: pass the policies " \
+          "as policies:, pass store_base_url: to Gitlab::Glaz::GovernPolicyEngine.new, or for the " \
+          "shared engine assign Gitlab::Glaz::GovernPolicyEngine.policy_store_url or set GLAZ_POLICY_STORE_URL " \
+          "(e.g. \"https://gitlab.com/api/v4\")"
+      end
+
+      def evaluation_request(trigger, context, principal, resource, data, store_authorization, policies, dry_run:)
+        require_policy_source!(policies)
+
+        ::Gitlab::Glaz::Govern::V1::EvaluateGovernPolicyRequest.encode(
+          ::Gitlab::Glaz::Govern::V1::EvaluateGovernPolicyRequest.new(
+            trigger: Validation.string!(trigger, "trigger"),
+            input_json: Validation.json!(context, "context"),
+            data_json: data.nil? ? "" : Validation.json!(data, "data"),
+            principal: Validation.string!(principal, "principal"),
+            resource: Validation.string!(resource, "resource"),
+            store_authorization: Validation.store_authorization!(store_authorization),
+            policies: Validation.policies!(policies),
+            dry_run: dry_run
+          )
+        )
+      end
+
+      def evaluation_result(response)
+        {
+          decisions: response.decisions.map { |decision| decision_hash(decision) },
+          undecided_policy_ids: response.undecided_policy_ids.to_a,
+          identifier: response.identifier,
+          dry_run: response.dry_run
+        }
+      end
+
       def build_native
         ::Glaz::Native::GovernPolicyEngine.new(@store_base_url, @connect_timeout_ms, @timeout_ms)
       end
@@ -322,10 +577,46 @@ module Gitlab
           matched: decision.matched,
           actions: decision.actions.map { |action| action_hash(action) },
           reasons: decision.reasons.map { |reason| reason_hash(reason) },
-          error: Validation.presence(decision.error)
+          error: Validation.presence(decision.error),
+          name: decision.name,
+          mode: Validation.mode_name(decision.mode),
+          violation_details: decision.violation_details.map { |detail| violation_detail_hash(detail) }
         }
       end
 
+      APPLICABILITIES = {
+        APPLICABILITY_APPLIES: "applies",
+        APPLICABILITY_NOT_APPLICABLE: "not_applicable",
+        APPLICABILITY_MIGHT_APPLY: "might_apply"
+      }.freeze
+      private_constant :APPLICABILITIES
+
+      # UNSPECIFIED is the engine's "not stated", which it sends only with an
+      # error. Without one it would read as an answer, so it is a fault.
+      def applicability_hash(row)
+        error = Validation.presence(row.error)
+        applicability = APPLICABILITIES[row.applicability]
+        if applicability.nil? && error.nil?
+          raise "policy #{row.policy_id} has no applicability and no error; got #{row.applicability.inspect}"
+        end
+
+        {
+          policy_id: row.policy_id,
+          name: row.name,
+          applicability: applicability,
+          missing_dimensions: row.missing_dimensions.to_a,
+          error: error
+        }
+      end
+
+      # +expected_json+ may encode a scalar, which json 2 parses as a
+      # document; +quirks_mode+ only matters to older json versions.
+      def violation_detail_hash(detail)
+        return { path: detail.path } if detail.expected_json.empty?
+
+        { path: detail.path, expected: JSON.parse(detail.expected_json, max_nesting: false, quirks_mode: true) }
+      end
+
       # The native layer already bounds nesting, so parse without a limit.
       def action_hash(action)
         {

data/lib/gitlab/glaz/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module Glaz
-    VERSION = "2.0.0"
+    VERSION = "2.2.0"
   end
 end

data/lib/gitlab/glaz.rb

@@ -16,7 +16,12 @@ module Gitlab
 
     # Returns the default roles embedded in the native extension at build time,
     # sourced from the glaz-roles crate's roles/**/*.yml definitions. Each entry
-    # is a hash: { id: String, name: String, permissions: Array<String> }.
+    # is a hash:
+    # { id: String, key: String, name: String, permissions: Array<String> }.
+    #
+    # :key is the role's stable machine identifier (e.g. "artifact_admin"):
+    # reference a role by it rather than hardcoding :id or matching on :name,
+    # which is human-facing and may be reworded.
     def roles
       @roles ||= ::Glaz.roles.each do |role|
         role[:permissions].freeze
@@ -27,7 +32,7 @@ module Gitlab
     # Returns GovernPolicyEngine.shared, the engine configured through
     # GovernPolicyEngine.policy_store_url= / GLAZ_POLICY_STORE_URL. It is
     # rebuilt when that configuration changes, so call this each time rather
-    # than caching the result.
+    # than caching the result. Not needed when #evaluate gets +policies:+.
     def govern_policy_engine
       GovernPolicyEngine.shared
     end

data/lib/proto/govern_pb.rb

@@ -1,33 +1,41 @@
 # frozen_string_literal: true
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
-# source: proto/govern.proto
+# source: gitlab/glaz/govern/v1/govern.proto
 
 require 'google/protobuf'
 
 
-descriptor_data = "\n\x12proto/govern.proto\x12\x0eglaz.govern.v1\"m\n EvaluateGovernPolicyDebugRequest\x12\x13\n\x0bpolicy_rego\x18\x01 \x01(\t\x12\r\n\x05query\x18\x02 \x01(\t\x12\x12\n\ninput_json\x18\x03 \x01(\t\x12\x11\n\tdata_json\x18\x04 \x01(\t\"Y\n\x0cGovernAction\x12\x13\n\x0b\x61\x63tion_type\x18\x01 \x01(\t\x12\x0f\n\x07message\x18\x02 \x01(\t\x12\x13\n\x0bparams_json\x18\x03 \x01(\t\x12\x0e\n\x06gating\x18\x04 \x01(\x08\"5\n\x0cGovernReason\x12\x0f\n\x07message\x18\x01 \x01(\t\x12\x14\n\x0c\x64\x65tails_json\x18\x02 \x01(\t\"2\n\x1bValidateGovernPolicyRequest\x12\x13\n\x0bpolicy_rego\x18\x01 \x01(\t\":\n\x15GovernValidationError\x12\x0f\n\x07message\x18\x01 \x01(\t\x12\x10\n\x08location\x18\x02 \x01(\t\"d\n\x1cValidateGovernPolicyResponse\x12\r\n\x05valid\x18\x01 \x01(\x08\x12\x35\n\x06\x65rrors\x18\x02 \x03(\x0b\x32%.glaz.govern.v1.GovernValidationError\"\x97\x01\n\x1b\x45valuateGovernPolicyRequest\x12\x0f\n\x07trigger\x18\x01 \x01(\t\x12\x12\n\ninput_json\x18\x02 \x01(\t\x12\x11\n\tdata_json\x18\x03 \x01(\t\x12\x11\n\tprincipal\x18\x04 \x01(\t\x12\x10\n\x08resource\x18\x05 \x01(\t\x12\x1b\n\x13store_authorization\x18\x06 \x01(\t\"]\n\x19ListGovernPoliciesRequest\x12\x0f\n\x07trigger\x18\x01 \x01(\t\x12\x12\n\ninput_json\x18\x02 \x01(\t\x12\x1b\n\x13store_authorization\x18\x03 \x01(\t\"\x97\x01\n\x13PolicyApplicability\x12\x11\n\tpolicy_id\x18\x01 \x01(\x04\x12\x0c\n\x04name\x18\x02 \x01(\t\x12\x34\n\rapplicability\x18\x03 \x01(\x0e\x32\x1d.glaz.govern.v1.Applicability\x12\x1a\n\x12missing_dimensions\x18\x04 \x03(\t\x12\r\n\x05\x65rror\x18\x05 \x01(\t\"S\n\x1aListGovernPoliciesResponse\x12\x35\n\x08policies\x18\x01 \x03(\x0b\x32#.glaz.govern.v1.PolicyApplicability\"\xa1\x01\n\x0ePolicyDecision\x12\x11\n\tpolicy_id\x18\x01 \x01(\x04\x12\x0f\n\x07matched\x18\x02 \x01(\x08\x12-\n\x07\x61\x63tions\x18\x03 \x03(\x0b\x32\x1c.glaz.govern.v1.GovernAction\x12-\n\x07reasons\x18\x04 \x03(\x0b\x32\x1c.glaz.govern.v1.GovernReason\x12\r\n\x05\x65rror\x18\x05 \x01(\t\"Q\n\x10GovernDiagnostic\x12,\n\x04kind\x18\x01 \x01(\x0e\x32\x1e.glaz.govern.v1.DiagnosticKind\x12\x0f\n\x07message\x18\x02 \x01(\t\"\xba\x01\n\x1c\x45valuateGovernPolicyResponse\x12\x31\n\tdecisions\x18\x01 \x03(\x0b\x32\x1e.glaz.govern.v1.PolicyDecision\x12\x1c\n\x14undecided_policy_ids\x18\x02 \x03(\x04\x12\x35\n\x0b\x64iagnostics\x18\x03 \x03(\x0b\x32 .glaz.govern.v1.GovernDiagnostic\x12\x12\n\nidentifier\x18\x04 \x01(\t*\x8a\x01\n\rApplicability\x12\x1d\n\x19\x41PPLICABILITY_UNSPECIFIED\x10\x00\x12\x19\n\x15\x41PPLICABILITY_APPLIES\x10\x01\x12 \n\x1c\x41PPLICABILITY_NOT_APPLICABLE\x10\x02\x12\x1d\n\x19\x41PPLICABILITY_MIGHT_APPLY\x10\x03*\x83\x01\n\x0e\x44iagnosticKind\x12\x1f\n\x1b\x44IAGNOSTIC_KIND_UNSPECIFIED\x10\x00\x12*\n&DIAGNOSTIC_KIND_INPUT_SCHEMA_VIOLATION\x10\x01\x12$\n DIAGNOSTIC_KIND_SCHEMA_NOT_FOUND\x10\x02\x42?Z=gitlab.com/gitlab-org/govern/glaz-client-go/governv1;governv1b\x06proto3"
+descriptor_data = "\n\"gitlab/glaz/govern/v1/govern.proto\x12\x15gitlab.glaz.govern.v1\"m\n EvaluateGovernPolicyDebugRequest\x12\x13\n\x0bpolicy_rego\x18\x01 \x01(\t\x12\r\n\x05query\x18\x02 \x01(\t\x12\x12\n\ninput_json\x18\x03 \x01(\t\x12\x11\n\tdata_json\x18\x04 \x01(\t\"Y\n\x0cGovernAction\x12\x13\n\x0b\x61\x63tion_type\x18\x01 \x01(\t\x12\x0f\n\x07message\x18\x02 \x01(\t\x12\x13\n\x0bparams_json\x18\x03 \x01(\t\x12\x0e\n\x06gating\x18\x04 \x01(\x08\"5\n\x0cGovernReason\x12\x0f\n\x07message\x18\x01 \x01(\t\x12\x14\n\x0c\x64\x65tails_json\x18\x02 \x01(\t\"C\n\x1bValidateGovernPolicyRequest\x12\x13\n\x0bpolicy_rego\x18\x01 \x01(\t\x12\x0f\n\x07trigger\x18\x02 \x01(\t\":\n\x15GovernValidationError\x12\x0f\n\x07message\x18\x01 \x01(\t\x12\x10\n\x08location\x18\x02 \x01(\t\"\xb4\x01\n\x1cValidateGovernPolicyResponse\x12\r\n\x05valid\x18\x01 \x01(\x08\x12<\n\x06\x65rrors\x18\x02 \x03(\x0b\x32,.gitlab.glaz.govern.v1.GovernValidationError\x12G\n\x11violation_details\x18\x03 \x03(\x0b\x32,.gitlab.glaz.govern.v1.GovernViolationDetail\"<\n\x15GovernViolationDetail\x12\x0c\n\x04path\x18\x01 \x01(\t\x12\x15\n\rexpected_json\x18\x02 \x01(\t\"=\n\x12GovernPolicyAction\x12\x13\n\x0b\x61\x63tion_type\x18\x01 \x01(\t\x12\x12\n\nvalue_json\x18\x02 \x01(\t\"&\n\x15GovernScopeDimensions\x12\r\n\x05paths\x18\x01 \x03(\t\"\xc3\x03\n\x0cGovernPolicy\x12\n\n\x02id\x18\x01 \x01(\x04\x12\x0c\n\x04name\x18\x02 \x01(\t\x12\x0f\n\x07trigger\x18\x03 \x01(\t\x12\x17\n\x0forganization_id\x18\x04 \x01(\x04\x12:\n\x04mode\x18\x05 \x01(\x0e\x32,.gitlab.glaz.govern.v1.GovernEnforcementMode\x12\x12\n\nscope_rego\x18\x06 \x01(\t\x12\x46\n\x10scope_dimensions\x18\x07 \x01(\x0b\x32,.gitlab.glaz.govern.v1.GovernScopeDimensions\x12\x13\n\x0bpolicy_rego\x18\x08 \x01(\t\x12:\n\x07\x61\x63tions\x18\t \x03(\x0b\x32).gitlab.glaz.govern.v1.GovernPolicyAction\x12\x16\n\x0cnamespace_id\x18\n \x01(\x04H\x00\x12\x1c\n\x12organization_level\x18\x0b \x01(\x08H\x00\x12G\n\x11violation_details\x18\x0c \x03(\x0b\x32,.gitlab.glaz.govern.v1.GovernViolationDetailB\x07\n\x05owner\"H\n\x0fGovernPolicySet\x12\x35\n\x08policies\x18\x01 \x03(\x0b\x32#.gitlab.glaz.govern.v1.GovernPolicy\"\xe2\x01\n\x1b\x45valuateGovernPolicyRequest\x12\x0f\n\x07trigger\x18\x01 \x01(\t\x12\x12\n\ninput_json\x18\x02 \x01(\t\x12\x11\n\tdata_json\x18\x03 \x01(\t\x12\x11\n\tprincipal\x18\x04 \x01(\t\x12\x10\n\x08resource\x18\x05 \x01(\t\x12\x1b\n\x13store_authorization\x18\x06 \x01(\t\x12\x38\n\x08policies\x18\x07 \x01(\x0b\x32&.gitlab.glaz.govern.v1.GovernPolicySet\x12\x0f\n\x07\x64ry_run\x18\x08 \x01(\x08\"\x97\x01\n\x19ListGovernPoliciesRequest\x12\x0f\n\x07trigger\x18\x01 \x01(\t\x12\x12\n\ninput_json\x18\x02 \x01(\t\x12\x1b\n\x13store_authorization\x18\x03 \x01(\t\x12\x38\n\x08policies\x18\x04 \x01(\x0b\x32&.gitlab.glaz.govern.v1.GovernPolicySet\"\x9e\x01\n\x13PolicyApplicability\x12\x11\n\tpolicy_id\x18\x01 \x01(\x04\x12\x0c\n\x04name\x18\x02 \x01(\t\x12;\n\rapplicability\x18\x03 \x01(\x0e\x32$.gitlab.glaz.govern.v1.Applicability\x12\x1a\n\x12missing_dimensions\x18\x04 \x03(\t\x12\r\n\x05\x65rror\x18\x05 \x01(\t\"Z\n\x1aListGovernPoliciesResponse\x12<\n\x08policies\x18\x01 \x03(\x0b\x32*.gitlab.glaz.govern.v1.PolicyApplicability\"\xc2\x02\n\x0ePolicyDecision\x12\x11\n\tpolicy_id\x18\x01 \x01(\x04\x12\x0f\n\x07matched\x18\x02 \x01(\x08\x12\x34\n\x07\x61\x63tions\x18\x03 \x03(\x0b\x32#.gitlab.glaz.govern.v1.GovernAction\x12\x34\n\x07reasons\x18\x04 \x03(\x0b\x32#.gitlab.glaz.govern.v1.GovernReason\x12\r\n\x05\x65rror\x18\x05 \x01(\t\x12\x0c\n\x04name\x18\x06 \x01(\t\x12:\n\x04mode\x18\x07 \x01(\x0e\x32,.gitlab.glaz.govern.v1.GovernEnforcementMode\x12G\n\x11violation_details\x18\x08 \x03(\x0b\x32,.gitlab.glaz.govern.v1.GovernViolationDetail\"X\n\x10GovernDiagnostic\x12\x33\n\x04kind\x18\x01 \x01(\x0e\x32%.gitlab.glaz.govern.v1.DiagnosticKind\x12\x0f\n\x07message\x18\x02 \x01(\t\"\xd9\x01\n\x1c\x45valuateGovernPolicyResponse\x12\x38\n\tdecisions\x18\x01 \x03(\x0b\x32%.gitlab.glaz.govern.v1.PolicyDecision\x12\x1c\n\x14undecided_policy_ids\x18\x02 \x03(\x04\x12<\n\x0b\x64iagnostics\x18\x03 \x03(\x0b\x32\'.gitlab.glaz.govern.v1.GovernDiagnostic\x12\x12\n\nidentifier\x18\x04 \x01(\t\x12\x0f\n\x07\x64ry_run\x18\x05 \x01(\x08*\xaa\x01\n\x15GovernEnforcementMode\x12\'\n#GOVERN_ENFORCEMENT_MODE_UNSPECIFIED\x10\x00\x12!\n\x1dGOVERN_ENFORCEMENT_MODE_AUDIT\x10\x01\x12 \n\x1cGOVERN_ENFORCEMENT_MODE_WARN\x10\x02\x12#\n\x1fGOVERN_ENFORCEMENT_MODE_ENFORCE\x10\x03*\x8a\x01\n\rApplicability\x12\x1d\n\x19\x41PPLICABILITY_UNSPECIFIED\x10\x00\x12\x19\n\x15\x41PPLICABILITY_APPLIES\x10\x01\x12 \n\x1c\x41PPLICABILITY_NOT_APPLICABLE\x10\x02\x12\x1d\n\x19\x41PPLICABILITY_MIGHT_APPLY\x10\x03*\x83\x01\n\x0e\x44iagnosticKind\x12\x1f\n\x1b\x44IAGNOSTIC_KIND_UNSPECIFIED\x10\x00\x12*\n&DIAGNOSTIC_KIND_INPUT_SCHEMA_VIOLATION\x10\x01\x12$\n DIAGNOSTIC_KIND_SCHEMA_NOT_FOUND\x10\x02\x62\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)
 
-module Glaz
-  module Govern
-    module V1
-      EvaluateGovernPolicyDebugRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.EvaluateGovernPolicyDebugRequest").msgclass
-      GovernAction = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.GovernAction").msgclass
-      GovernReason = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.GovernReason").msgclass
-      ValidateGovernPolicyRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.ValidateGovernPolicyRequest").msgclass
-      GovernValidationError = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.GovernValidationError").msgclass
-      ValidateGovernPolicyResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.ValidateGovernPolicyResponse").msgclass
-      EvaluateGovernPolicyRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.EvaluateGovernPolicyRequest").msgclass
-      ListGovernPoliciesRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.ListGovernPoliciesRequest").msgclass
-      PolicyApplicability = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.PolicyApplicability").msgclass
-      ListGovernPoliciesResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.ListGovernPoliciesResponse").msgclass
-      PolicyDecision = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.PolicyDecision").msgclass
-      GovernDiagnostic = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.GovernDiagnostic").msgclass
-      EvaluateGovernPolicyResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.EvaluateGovernPolicyResponse").msgclass
-      Applicability = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.Applicability").enummodule
-      DiagnosticKind = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.DiagnosticKind").enummodule
+module Gitlab
+  module Glaz
+    module Govern
+      module V1
+        EvaluateGovernPolicyDebugRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.EvaluateGovernPolicyDebugRequest").msgclass
+        GovernAction = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernAction").msgclass
+        GovernReason = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernReason").msgclass
+        ValidateGovernPolicyRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.ValidateGovernPolicyRequest").msgclass
+        GovernValidationError = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernValidationError").msgclass
+        ValidateGovernPolicyResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.ValidateGovernPolicyResponse").msgclass
+        GovernViolationDetail = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernViolationDetail").msgclass
+        GovernPolicyAction = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernPolicyAction").msgclass
+        GovernScopeDimensions = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernScopeDimensions").msgclass
+        GovernPolicy = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernPolicy").msgclass
+        GovernPolicySet = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernPolicySet").msgclass
+        EvaluateGovernPolicyRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.EvaluateGovernPolicyRequest").msgclass
+        ListGovernPoliciesRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.ListGovernPoliciesRequest").msgclass
+        PolicyApplicability = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.PolicyApplicability").msgclass
+        ListGovernPoliciesResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.ListGovernPoliciesResponse").msgclass
+        PolicyDecision = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.PolicyDecision").msgclass
+        GovernDiagnostic = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernDiagnostic").msgclass
+        EvaluateGovernPolicyResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.EvaluateGovernPolicyResponse").msgclass
+        GovernEnforcementMode = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.GovernEnforcementMode").enummodule
+        Applicability = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.Applicability").enummodule
+        DiagnosticKind = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("gitlab.glaz.govern.v1.DiagnosticKind").enummodule
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-glaz
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: x86_64-linux-gnu
 authors:
 - group::authorization
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf