gitlab-glaz 1.0.0 → 1.2.0

data/Cargo.toml

@@ -4,12 +4,14 @@ members = ["ext/*"]
 resolver = "2"
 
 [workspace.package]
-version = "1.0.0"
+version = "1.2.0"
 edition = "2024"
 
 # Shared dependencies for all crates
 [workspace.dependencies]
 magnus = { version = "0.8.2", features = ["rb-sys"] }
 rb-sys = "0.9.128"
-glaz-module = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "13a32ad3f0e6490384afb6ba6a3c3e2a6439901a" }
-glaz-roles = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "13a32ad3f0e6490384afb6ba6a3c3e2a6439901a" }
+prost = "0.14"
+glaz-module = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "af9019a186fbb42cede0ad5ba7496aff2f88cb41" }
+glaz-roles = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "af9019a186fbb42cede0ad5ba7496aff2f88cb41" }
+glaz-proto = { git = "https://gitlab.com/gitlab-org/auth/glaz.git", rev = "af9019a186fbb42cede0ad5ba7496aff2f88cb41" }

data/README.md

@@ -35,7 +35,7 @@ engine.load_policies(new_cedar_policies)
 
 The schema is loaded once at construction and cannot change; build a new engine to use a new schema.
 
-Schemas must declare `User` and `Resource` entities (checks build `User::"<subject_uuid>"` and `Resource::"<object_uuid>"` UIDs), and every action's context type must include `user_permissions: Set<Action>`, which the engine injects with the checked action.
+Schemas must declare `User` and `Resource` entities (checks build `User::"<subject_uuid>"` and `Resource::"<object_uuid>"` UIDs), and every action's context type must include `permissions: Set<Action>`, which the engine injects with the checked action.
 
 ## Development
 

data/ext/glaz/Cargo.toml

@@ -9,5 +9,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 glaz-module = { workspace = true }
+glaz-proto = { workspace = true }
 glaz-roles = { workspace = true }
 magnus = { workspace = true }
+prost = { workspace = true }

data/ext/glaz/src/lib.rs

@@ -1,4 +1,5 @@
 use magnus::{Error, Ruby, prelude::*};
+use prost::Message;
 
 /// Thin 1:1 wrapper around `glaz_module::PermissionCheckEngine`. The engine
 /// starts empty; `load_schema` must be called before `load_policies`, and
@@ -51,6 +52,93 @@ impl PermissionCheckEngine {
     }
 }
 
+/// Thin 1:1 wrapper around `glaz_module::GovernPolicyCheckEngine`, the Rego
+/// governance evaluator. Stateless between calls; `evaluate` raises on
+/// failure (matching `PermissionCheckEngine`'s convention) and returns the
+/// encoded `EvaluateGovernPolicyResponse` on success — `ArgumentError` for
+/// bad policy/input, `RuntimeError` for an engine-side fault, see
+/// `map_error`; `debug_evaluate` is infallible and carries failures in-band
+/// in its JSON response instead, since it's a raw debugging escape hatch;
+/// `validate` is also infallible — policy errors are returned as
+/// `Ok(valid: false, errors: [...])` so the Policy Store can surface
+/// actionable feedback without treating a user mistake as an exceptional
+/// condition; a malformed protobuf payload raises `ArgumentError`, while
+/// internal engine failures (`NotInitialized`, `Runtime`) raise
+/// `RuntimeError` via `map_error`.
+///
+/// Registered as `Glaz::Native::GovernPolicyEngine` (not
+/// `Glaz::GovernPolicyEngine`) specifically to avoid colliding, in name,
+/// with the polished `Gitlab::Glaz::GovernPolicyEngine` wrapper — this
+/// class is raw FFI plumbing; prefer the wrapper unless you specifically
+/// need `debug_evaluate`.
+#[magnus::wrap(class = "Glaz::Native::GovernPolicyEngine")]
+struct GovernPolicyEngine {
+    engine: glaz_module::GovernPolicyCheckEngine,
+}
+
+impl GovernPolicyEngine {
+    fn initialize() -> Self {
+        Self {
+            engine: glaz_module::GovernPolicyCheckEngine::new(),
+        }
+    }
+
+    /// Evaluate using the request's `query` field. `query` must be
+    /// non-blank; a blank query is reported in-band as an error rather than
+    /// falling back to discovery (use `evaluate` for that).
+    fn debug_evaluate(
+        ruby: &Ruby,
+        rb_self: &Self,
+        proto_bytes: magnus::RString,
+    ) -> Result<magnus::RString, Error> {
+        let bytes = unsafe { proto_bytes.as_slice() };
+        let response = rb_self.engine.debug_evaluate(bytes);
+        Ok(ruby.str_from_slice(&response))
+    }
+
+    /// Evaluate by auto-discovering the policy's `violation`, `deny`,
+    /// and/or `allow` rules. The request's `query` field is ignored.
+    ///
+    /// Raises on any evaluation failure rather than returning an in-band
+    /// error, matching `PermissionCheckEngine#check_action`'s convention.
+    /// `map_error` raises `ArgumentError` for malformed protobuf, invalid
+    /// policy, oversized documents, undefined results, or an unrecognized
+    /// result shape - all caller-fixable - and `RuntimeError` for an
+    /// engine-side fault (e.g. the Rego evaluation time budget was
+    /// exceeded), which is not.
+    fn evaluate(
+        ruby: &Ruby,
+        rb_self: &Self,
+        proto_bytes: magnus::RString,
+    ) -> Result<magnus::RString, Error> {
+        let bytes = unsafe { proto_bytes.as_slice() };
+        let response = rb_self
+            .engine
+            .evaluate(bytes)
+            .map_err(|e| map_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&response.encode_to_vec()))
+    }
+
+    /// Parse and compile a Rego policy without evaluating it against input.
+    ///
+    /// Infallible for policy errors: parse failures and oversized input are
+    /// returned in-band as `{ valid: false, errors: [...] }` rather than
+    /// raised. Only a malformed protobuf payload raises `ArgumentError`; an
+    /// internal engine fault raises `RuntimeError` via `map_error`.
+    fn validate(
+        ruby: &Ruby,
+        rb_self: &Self,
+        proto_bytes: magnus::RString,
+    ) -> Result<magnus::RString, Error> {
+        let bytes = unsafe { proto_bytes.as_slice() };
+        let response = rb_self
+            .engine
+            .validate(bytes)
+            .map_err(|e| map_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&response.encode_to_vec()))
+    }
+}
+
 /// Return the default roles embedded in the extension at build time (parsed
 /// from glaz-roles' roles/**/*.yml) as an array of hashes shaped like
 /// `{ id: String, name: String, permissions: [String, ...] }`.
@@ -100,5 +188,14 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "check_action",
         magnus::method!(PermissionCheckEngine::check_action, 1),
     )?;
+    let native = glaz.define_module("Native")?;
+    let govern = native.define_class("GovernPolicyEngine", ruby.class_object())?;
+    govern.define_singleton_method("new", magnus::function!(GovernPolicyEngine::initialize, 0))?;
+    govern.define_method(
+        "debug_evaluate",
+        magnus::method!(GovernPolicyEngine::debug_evaluate, 1),
+    )?;
+    govern.define_method("evaluate", magnus::method!(GovernPolicyEngine::evaluate, 1))?;
+    govern.define_method("validate", magnus::method!(GovernPolicyEngine::validate, 1))?;
     Ok(())
 }

data/lib/gitlab/glaz/engine.rb

@@ -15,9 +15,9 @@ module Gitlab
     # each checkable action with `appliesTo { principal: [User], resource:
     # [Resource], ... }`, because the engine builds `User::"<subject_uuid>"` and
     # `Resource::"<object_uuid>"` entity UIDs for every check. The engine also
-    # injects `user_permissions` (a Set<Action> containing the checked action)
+    # injects `permissions` (a Set<Action> containing the checked action)
     # into the Cedar context, so an action's declared context type must include
-    # `user_permissions: Set<Action>` alongside any custom attributes.
+    # `permissions: Set<Action>` alongside any custom attributes.
     class Engine
       # @param schema [String] Cedar schema source (`.cedarschema` DSL).
       # @param policies [String] Cedar policy source, validated against the

data/lib/gitlab/glaz/govern_policy_engine.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gitlab
+  module Glaz
+    # Wraps a native Glaz::Native::GovernPolicyEngine instance - the Rego
+    # governance policy evaluator.
+    #
+    # The evaluator is a pure function over its arguments: it performs no
+    # I/O, holds no state between calls, and executes no actions. The caller
+    # supplies the policy's Rego source and the assembled context document,
+    # and is responsible for executing the returned actions.
+    #
+    # +reasons+ and +actions+ are independent, not 1:1: +reasons+ reports why
+    # the policy matched - one entry per `violation`/`deny` element the
+    # policy produced; empty means it did not match - while +actions+
+    # reports what to enforce as a result. Actions are conceptually owned by
+    # the policy's configuration in the future central Policy Store, so any
+    # match currently yields a single synthesized block action regardless of
+    # how many reasons fired. +matched+ is a convenience boolean mirroring
+    # "+actions+ is non-empty", for callers who don't want to infer that
+    # from array emptiness themselves.
+    #
+    # #evaluate is the primary path: it always auto-discovers the policy's
+    # `violation`/`deny`/`allow` rules (the native +evaluate+ path), returns
+    # the hardened Hash shape described below on success, and raises on any
+    # evaluation failure - the native call itself raises ArgumentError for
+    # bad policy/input and RuntimeError for an engine-side fault; see
+    # #evaluate's own doc comment.
+    # #debug_evaluate is a separate, secondary method for debugging/testing a Rego query
+    # directly: it performs no violation/deny/allow interpretation, does
+    # not raise, and returns whatever the query evaluated to (plus any
+    # error, in-band) with no guarantee about its shape.
+    class GovernPolicyEngine
+      def initialize
+        @native = ::Glaz::Native::GovernPolicyEngine.new
+      end
+
+      # Evaluate a Rego governance policy against context.
+      #
+      # @param policy_rego [String] Rego policy text (max 64 KiB).
+      # @param context [Hash] the host-assembled context, passed to the
+      #   policy as the Rego `input` document (max 1 MiB as JSON).
+      # @param data [Hash] optional precomputed Rego `data` document (e.g.
+      #   cached settings or scan results). Top-level keys must not collide
+      #   with the policy's package path.
+      # @raise [ArgumentError] for a caller-fixable evaluation failure -
+      #   malformed policy, oversized documents, an unrecognized
+      #   violation/deny/allow shape, and so on.
+      # @raise [RuntimeError] for an engine-side fault, e.g. the Rego
+      #   evaluation time budget was exceeded - not the caller's fault.
+      #   Callers can rely on a successful return meaning the policy
+      #   evaluated cleanly; there is no in-band error to check.
+      # @return [Hash] `{ matched: Boolean, actions: Array<Hash>, reasons:
+      #   Array<Hash> }`. `matched` is `true` exactly when `actions`
+      #   (equivalently `reasons`) is non-empty - a convenience so callers
+      #   don't have to infer "did the policy fire" from array emptiness.
+      #   It is not itself an allow/deny decision: today every action is
+      #   `"block"`, so `matched` and "should deny" coincide, but a future
+      #   Policy Store action type (e.g. `"log"`) could match without
+      #   implying denial - check `actions` for enforcement decisions. Each
+      #   action is `{ action_type: String, message: String | nil, params:
+      #   Hash }`; each reason is `{ message: String | nil, details: Hash
+      #   }`. Empty +actions+ means the policy allows the operation.
+      def evaluate(policy_rego:, context:, data: {})
+        encoded = ::Glaz::Govern::V1::EvaluateGovernPolicyRequest.encode(
+          ::Glaz::Govern::V1::EvaluateGovernPolicyRequest.new(
+            policy_rego: policy_rego,
+            input_json: context.to_json,
+            data_json: data.nil? || data.empty? ? "" : data.to_json
+          )
+        )
+
+        response = ::Glaz::Govern::V1::EvaluateGovernPolicyResponse.decode(
+          @native.evaluate(encoded)
+        )
+
+        {
+          matched: response.matched,
+          reasons: response.reasons.map { |reason| reason_hash(reason) },
+          actions: response.actions.map { |action| action_hash(action) }
+        }
+      end
+
+      # Validate a Rego policy at save time without evaluating it against input.
+      #
+      # Parses and compiles the policy source. A policy that fails to parse is
+      # not an error - it is returned as `{ valid: false, errors: [...] }` so
+      # the Policy Store can surface actionable feedback without treating a user
+      # mistake as an exceptional condition.
+      #
+      # @param policy_rego [String] Rego policy source text (UTF-8, max 64 KiB).
+      #   Must be a valid UTF-8 string; raises `Encoding::InvalidByteSequenceError`
+      #   if the string contains invalid byte sequences.
+      # @return [Hash] `{ valid: Boolean, errors: Array<Hash> }`.
+      #   `valid` is `true` when the policy parsed and compiled successfully.
+      #   `errors` is empty when valid; each entry is
+      #   `{ message: String, location: String }` where `location` is a
+      #   source-location hint in `"LINE:COL"` format (e.g. `"2:1"`) when the
+      #   engine surfaces one, or `""` when no separate location is available.
+      def validate(policy_rego:)
+        encoded = ::Glaz::Govern::V1::ValidateGovernPolicyRequest.encode(
+          ::Glaz::Govern::V1::ValidateGovernPolicyRequest.new(
+            policy_rego: policy_rego
+          )
+        )
+
+        response = ::Glaz::Govern::V1::ValidateGovernPolicyResponse.decode(
+          @native.validate(encoded)
+        )
+
+        {
+          valid: response.valid,
+          errors: response.errors.map { |e| { message: e.message, location: e.location } }
+        }
+      end
+
+      # Evaluate a Rego query directly, with no `violation`/`deny`/`allow`
+      # interpretation. A debugging/testing escape hatch for exercising a
+      # policy's Rego directly; prefer #evaluate for the primary path.
+      # Unlike #evaluate, this does not raise on failure - +error+ stays
+      # in-band, since this method is meant for inspecting raw results
+      # (including failures) while developing a policy, not for production
+      # decision-making.
+      #
+      # @param policy_rego [String] Rego policy text (max 64 KiB).
+      # @param context [Hash] the host-assembled context, passed to the
+      #   policy as the Rego `input` document (max 1 MiB as JSON).
+      # @param query [String] Rego query to evaluate (e.g.
+      #   "data.mypackage.violation"); must not be blank.
+      # @param data [Hash] optional precomputed Rego `data` document.
+      # @return [Hash] `{ result: Object, error: String | nil }` - `result`
+      #   is exactly whatever `query` evaluated to (parsed JSON), with no
+      #   guarantee about its shape. A non-nil `error` means evaluation
+      #   failed; `result` is then `nil`.
+      def debug_evaluate(policy_rego:, context:, query:, data: {})
+        encoded = ::Glaz::Govern::V1::EvaluateGovernPolicyDebugRequest.encode(
+          ::Glaz::Govern::V1::EvaluateGovernPolicyDebugRequest.new(
+            policy_rego: policy_rego,
+            query: query.to_s,
+            input_json: context.to_json,
+            data_json: data.nil? || data.empty? ? "" : data.to_json
+          )
+        )
+
+        response = JSON.parse(@native.debug_evaluate(encoded), symbolize_names: true)
+
+        {
+          result: response[:result],
+          error: response[:error].nil? || response[:error].empty? ? nil : response[:error]
+        }
+      end
+
+      private
+
+      def action_hash(action)
+        {
+          action_type: action.action_type,
+          message: action.message.empty? ? nil : action.message,
+          params: JSON.parse(action.params_json)
+        }
+      end
+
+      def reason_hash(reason)
+        {
+          message: reason.message.empty? ? nil : reason.message,
+          details: JSON.parse(reason.details_json)
+        }
+      end
+    end
+  end
+end

data/lib/gitlab/glaz/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module Glaz
-    VERSION = "1.0.0"
+    VERSION = "1.2.0"
   end
 end

data/lib/gitlab/glaz.rb

@@ -3,10 +3,12 @@
 require_relative "glaz/version"
 require_relative 'glaz/loader'
 require "proto/service_pb"
+require "proto/govern_pb"
 
 load_rust_extension
 
 require_relative "glaz/engine"
+require_relative "glaz/govern_policy_engine"
 
 module Gitlab
   module Glaz
@@ -21,5 +23,13 @@ module Gitlab
         role.freeze
       end.freeze
     end
+
+    # Returns the shared Gitlab::Glaz::GovernPolicyEngine instance, memoized
+    # across calls. Evaluate Rego governance policies via
+    # +govern_policy_engine.evaluate+; see GovernPolicyEngine#evaluate for
+    # the full contract.
+    def govern_policy_engine
+      @govern_policy_engine ||= GovernPolicyEngine.new
+    end
   end
 end

data/lib/proto/govern_pb.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: proto/govern.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x12proto/govern.proto\x12\x0eglaz.govern.v1\"z\n\x1bEvaluateGovernPolicyRequest\x12\x1f\n\x0bpolicy_rego\x18\x01 \x01(\tR\npolicyRego\x12\x1d\n\ninput_json\x18\x02 \x01(\tR\tinputJson\x12\x1b\n\tdata_json\x18\x03 \x01(\tR\x08dataJson\"\x95\x01\n EvaluateGovernPolicyDebugRequest\x12\x1f\n\x0bpolicy_rego\x18\x01 \x01(\tR\npolicyRego\x12\x14\n\x05query\x18\x02 \x01(\tR\x05query\x12\x1d\n\ninput_json\x18\x03 \x01(\tR\tinputJson\x12\x1b\n\tdata_json\x18\x04 \x01(\tR\x08dataJson\"j\n\x0cGovernAction\x12\x1f\n\x0baction_type\x18\x01 \x01(\tR\nactionType\x12\x18\n\x07message\x18\x02 \x01(\tR\x07message\x12\x1f\n\x0bparams_json\x18\x03 \x01(\tR\nparamsJson\"K\n\x0cGovernReason\x12\x18\n\x07message\x18\x01 \x01(\tR\x07message\x12!\n\x0cdetails_json\x18\x02 \x01(\tR\x0bdetailsJson\"\xa8\x01\n\x1cEvaluateGovernPolicyResponse\x126\n\x07actions\x18\x01 \x03(\x0b2\x1c.glaz.govern.v1.GovernActionR\x07actions\x126\n\x07reasons\x18\x02 \x03(\x0b2\x1c.glaz.govern.v1.GovernReasonR\x07reasons\x12\x18\n\x07matched\x18\x03 \x01(\x08R\x07matched\">\n\x1bValidateGovernPolicyRequest\x12\x1f\n\x0bpolicy_rego\x18\x01 \x01(\tR\npolicyRego\"M\n\x15GovernValidationError\x12\x18\n\x07message\x18\x01 \x01(\tR\x07message\x12\x1a\n\x08location\x18\x02 \x01(\tR\x08location\"s\n\x1cValidateGovernPolicyResponse\x12\x14\n\x05valid\x18\x01 \x01(\x08R\x05valid\x12=\n\x06errors\x18\x02 \x03(\x0b2%.glaz.govern.v1.GovernValidationErrorR\x06errorsb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Glaz
+  module Govern
+    module V1
+      EvaluateGovernPolicyRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.EvaluateGovernPolicyRequest").msgclass
+      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
+      EvaluateGovernPolicyResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("glaz.govern.v1.EvaluateGovernPolicyResponse").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
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-glaz
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - group::authorization
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -98,8 +98,10 @@ files:
 - ext/glaz/src/lib.rs
 - lib/gitlab/glaz.rb
 - lib/gitlab/glaz/engine.rb
+- lib/gitlab/glaz/govern_policy_engine.rb
 - lib/gitlab/glaz/loader.rb
 - lib/gitlab/glaz/version.rb
+- lib/proto/govern_pb.rb
 - lib/proto/relationships/relationships_pb.rb
 - lib/proto/service_pb.rb
 homepage: https://gitlab.com/gitlab-org/ruby/gems/gitlab-glaz
@@ -114,7 +116,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="