gitlab-glaz 1.0.0-aarch64-linux-gnu → 1.1.0-aarch64-linux-gnu

data/Cargo.toml

@@ -4,12 +4,14 @@ members = ["ext/*"]
 resolver = "2"
 
 [workspace.package]
-version = "1.0.0"
+version = "1.1.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,69 @@ impl PermissionCheckEngine {
     }
 }
 
+/// Thin 1:1 wrapper around `glaz_module::GovernPolicyCheckEngine`, the Rego
+/// governance evaluator. Stateless between calls; both methods take an
+/// encoded `glaz.govern.v1.EvaluateGovernPolicyRequest`. `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.
+///
+/// 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()))
+    }
+}
+
 /// 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 +164,13 @@ 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))?;
     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,140 @@
+# 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
+
+      # 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.1.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,23 @@
+# 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\"Y\n\x1b\x45valuateGovernPolicyRequest\x12\x13\n\x0bpolicy_rego\x18\x01 \x01(\t\x12\x12\n\ninput_json\x18\x02 \x01(\t\x12\x11\n\tdata_json\x18\x03 \x01(\t\"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\"I\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\"5\n\x0cGovernReason\x12\x0f\n\x07message\x18\x01 \x01(\t\x12\x14\n\x0c\x64\x65tails_json\x18\x02 \x01(\t\"\x8d\x01\n\x1c\x45valuateGovernPolicyResponse\x12-\n\x07\x61\x63tions\x18\x01 \x03(\x0b\x32\x1c.glaz.govern.v1.GovernAction\x12-\n\x07reasons\x18\x02 \x03(\x0b\x32\x1c.glaz.govern.v1.GovernReason\x12\x0f\n\x07matched\x18\x03 \x01(\x08\x62\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
+    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.1.0
 platform: aarch64-linux-gnu
 authors:
 - group::authorization
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -102,8 +102,10 @@ files:
 - lib/gitlab/glaz/3.4/glaz.so
 - lib/gitlab/glaz/4.0/glaz.so
 - 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