opa-golib-python-bindings 0.4.0__tar.gz → 0.4.2__tar.gz

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opa-golib-python-bindings
-Version: 0.4.0
+Version: 0.4.2
 Summary: Python bindings for the OPA (Open Policy Agent) Rego engine via a Go c-shared library
 Project-URL: Homepage, https://github.com/phi1010/opa-golib-python-bindings
 Project-URL: Repository, https://github.com/phi1010/opa-golib-python-bindings
@@ -63,6 +63,10 @@ Notes:
 
 - `add_data` deep-merges objects; identical values coexist, conflicting values raise
   `OpaError(code="merge_conflict")` naming the conflicting path.
+- A Go-side panic in any bridge call surfaces as `OpaError(code="panic")`
+  instead of killing the process; the engine stays usable afterwards. (The
+  bridge also validates `compile_filters(mappings=...)` values are strings
+  and rejects malformed shapes with `OpaError(code="invalid_json")`.)
 - `register_function` infers arity from the callable's signature. A `*args` function is
   variadic and is called from Rego with a single array argument: `many(["a", "b"])`
   (OPA does not support variadic builtins with return values).
@@ -131,3 +135,22 @@ Notes:
 - Rego `print(...)` output is captured per evaluation: set `engine.print_handler`
   to a `callable(message, location)` to receive it (default: written to stderr);
   `engine.last_prints` holds the `(message, location)` pairs of the last eval.
+- **Concurrency:** an engine may be shared across threads — evals are
+  serialized by an internal re-entrant lock (builtins may evaluate on their
+  own engine). Per-eval state (`last_trace`, `last_coverage`, `last_prints`)
+  reflects the most recently *completed* eval, so with a shared engine prefer
+  return values over `last_*` attributes, or use one engine per thread.
+- **Resource limits / DoS:** there are no built-in caps. Policy/data sizes,
+  the number of engines (call `close()`; `__del__` is best-effort under GC),
+  and the set of distinct query strings (each is cached as a prepared query
+  on the engine, invalidated by any config change) are bounded only by the
+  process. If queries are dynamic or attacker-shaped, cap and canonicalize
+  them in the application; treat `query`, `policy source`, and `data` as
+  privileged inputs on a multi-tenant host. Rego itself can loop/compute
+  without limits, so the caller should apply timeouts/load controls at the
+  application layer if policies are untrusted.
+- **Confidentiality:** traces (`trace=True`) capture the plugged values of
+  local variables, and Rego `print()` calls see their arguments; both can
+  contain secrets from `input` or `data`. Keep them off shared logs, or
+  scrub them, when evaluating sensitive inputs. (The default print handler
+  writes to stderr.)

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/README.md

@@ -37,6 +37,10 @@ Notes:
 
 - `add_data` deep-merges objects; identical values coexist, conflicting values raise
   `OpaError(code="merge_conflict")` naming the conflicting path.
+- A Go-side panic in any bridge call surfaces as `OpaError(code="panic")`
+  instead of killing the process; the engine stays usable afterwards. (The
+  bridge also validates `compile_filters(mappings=...)` values are strings
+  and rejects malformed shapes with `OpaError(code="invalid_json")`.)
 - `register_function` infers arity from the callable's signature. A `*args` function is
   variadic and is called from Rego with a single array argument: `many(["a", "b"])`
   (OPA does not support variadic builtins with return values).
@@ -105,3 +109,22 @@ Notes:
 - Rego `print(...)` output is captured per evaluation: set `engine.print_handler`
   to a `callable(message, location)` to receive it (default: written to stderr);
   `engine.last_prints` holds the `(message, location)` pairs of the last eval.
+- **Concurrency:** an engine may be shared across threads — evals are
+  serialized by an internal re-entrant lock (builtins may evaluate on their
+  own engine). Per-eval state (`last_trace`, `last_coverage`, `last_prints`)
+  reflects the most recently *completed* eval, so with a shared engine prefer
+  return values over `last_*` attributes, or use one engine per thread.
+- **Resource limits / DoS:** there are no built-in caps. Policy/data sizes,
+  the number of engines (call `close()`; `__del__` is best-effort under GC),
+  and the set of distinct query strings (each is cached as a prepared query
+  on the engine, invalidated by any config change) are bounded only by the
+  process. If queries are dynamic or attacker-shaped, cap and canonicalize
+  them in the application; treat `query`, `policy source`, and `data` as
+  privileged inputs on a multi-tenant host. Rego itself can loop/compute
+  without limits, so the caller should apply timeouts/load controls at the
+  application layer if policies are untrusted.
+- **Confidentiality:** traces (`trace=True`) capture the plugged values of
+  local variables, and Rego `print()` calls see their arguments; both can
+  contain secrets from `input` or `data`. Keep them off shared logs, or
+  scrub them, when evaluating sensitive inputs. (The default print handler
+  writes to stderr.)

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/go/bridge.go

@@ -5,9 +5,10 @@ package main
 
 // Callback provided by the host (Python). It receives the engine handle, the
 // builtin name and the arguments as a JSON array. It returns a pointer to a
-// JSON envelope {"result": ...} or {"error": "..."}. The buffer is owned by
-// the host and must stay valid until the callback is invoked again; the Go
-// side copies it synchronously.
+// malloc'd JSON envelope {"result": ...} or {"error": "..."}. Ownership of the
+// buffer transfers to the Go side, which copies it synchronously and frees it
+// with the C allocator (see builtins.go). The host must not retain or reuse
+// the pointer after the callback returns.
 typedef char* (*opa_callback)(unsigned long long h, char* name, char* argsJson);
 */
 import "C"
@@ -92,6 +93,18 @@ func errorJSON(code, msg string) *C.char {
 	return C.CString(string(b))
 }
 
+// guard converts a panic in fn into a JSON error instead of letting it kill
+// the whole host process. Panics may fire while e.mu is held; deferred
+// unlocks still run during unwinding, so the engine stays usable.
+func guard(fn func() *C.char) (r *C.char) {
+	defer func() {
+		if rec := recover(); rec != nil {
+			r = errorJSON("panic", fmt.Sprint(rec))
+		}
+	}()
+	return fn()
+}
+
 //export OpaNew
 func OpaNew() C.ulonglong {
 	registryMu.Lock()
@@ -107,6 +120,7 @@ func OpaNew() C.ulonglong {
 
 //export OpaDestroy
 func OpaDestroy(h C.ulonglong) {
+	defer func() { recover() }() // keep the host alive on any internal panic
 	registryMu.Lock()
 	defer registryMu.Unlock()
 	delete(registry, uint64(h))
@@ -114,11 +128,16 @@ func OpaDestroy(h C.ulonglong) {
 
 //export OpaFreeString
 func OpaFreeString(s *C.char) {
+	defer func() { recover() }()
 	C.free(unsafe.Pointer(s))
 }
 
 //export OpaAddPolicy
 func OpaAddPolicy(h C.ulonglong, path, src *C.char) *C.char {
+	return guard(func() *C.char { return opaAddPolicy(h, path, src) })
+}
+
+func opaAddPolicy(h C.ulonglong, path, src *C.char) *C.char {
 	e, err := getEngine(h)
 	if err != nil {
 		return errorJSON("invalid_handle", err.Error())
@@ -136,6 +155,10 @@ func OpaAddPolicy(h C.ulonglong, path, src *C.char) *C.char {
 
 //export OpaAddData
 func OpaAddData(h C.ulonglong, dataPath, jsonValue *C.char) *C.char {
+	return guard(func() *C.char { return opaAddData(h, dataPath, jsonValue) })
+}
+
+func opaAddData(h C.ulonglong, dataPath, jsonValue *C.char) *C.char {
 	e, err := getEngine(h)
 	if err != nil {
 		return errorJSON("invalid_handle", err.Error())
@@ -170,6 +193,10 @@ func OpaAddData(h C.ulonglong, dataPath, jsonValue *C.char) *C.char {
 
 //export OpaRegisterBuiltin
 func OpaRegisterBuiltin(h C.ulonglong, name *C.char, arity C.int, cb C.opa_callback) *C.char {
+	return guard(func() *C.char { return opaRegisterBuiltin(h, name, arity, cb) })
+}
+
+func opaRegisterBuiltin(h C.ulonglong, name *C.char, arity C.int, cb C.opa_callback) *C.char {
 	e, err := getEngine(h)
 	if err != nil {
 		return errorJSON("invalid_handle", err.Error())
@@ -189,17 +216,21 @@ func OpaRegisterBuiltin(h C.ulonglong, name *C.char, arity C.int, cb C.opa_callb
 
 //export OpaEvalQuery
 func OpaEvalQuery(h C.ulonglong, query, inputJson *C.char, coverage, trace C.int) *C.char {
-	return evalCommon(h, C.GoString(query), inputJson, coverage != 0, trace != 0)
+	return guard(func() *C.char {
+		return evalCommon(h, C.GoString(query), inputJson, coverage != 0, trace != 0)
+	})
 }
 
 //export OpaEvalDocument
 func OpaEvalDocument(h C.ulonglong, docPath, inputJson *C.char, coverage, trace C.int) *C.char {
-	p := C.GoString(docPath)
-	q := "data"
-	if p != "" {
-		q = "data." + p
-	}
-	return evalCommon(h, q, inputJson, coverage != 0, trace != 0)
+	return guard(func() *C.char {
+		p := C.GoString(docPath)
+		q := "data"
+		if p != "" {
+			q = "data." + p
+		}
+		return evalCommon(h, q, inputJson, coverage != 0, trace != 0)
+	})
 }
 
 func evalCommon(h C.ulonglong, query string, inputJson *C.char, coverage, trace bool) *C.char {
@@ -207,9 +238,12 @@ func evalCommon(h C.ulonglong, query string, inputJson *C.char, coverage, trace
 	if err != nil {
 		return errorJSON("invalid_handle", err.Error())
 	}
-	e.mu.Lock()
-	pq, ok := e.prepared[query]
-	if !ok {
+	pq, err := func() (rego.PreparedEvalQuery, error) {
+		e.mu.Lock()
+		defer e.mu.Unlock()
+		if pq, ok := e.prepared[query]; ok {
+			return pq, nil
+		}
 		opts := []func(*rego.Rego){
 			rego.Query(query),
 			rego.Store(inmem.NewFromObject(e.data)),
@@ -222,14 +256,17 @@ func evalCommon(h C.ulonglong, query string, inputJson *C.char, coverage, trace
 		for _, b := range e.builtins {
 			opts = append(opts, makeBuiltin(uint64(h), b))
 		}
-		pq, err = rego.New(opts...).PrepareForEval(context.Background())
+		pq, err := rego.New(opts...).PrepareForEval(context.Background())
 		if err != nil {
-			e.mu.Unlock()
-			return errorJSON("prepare_error", err.Error())
+			var zero rego.PreparedEvalQuery
+			return zero, err
 		}
 		e.prepared[query] = pq
+		return pq, nil
+	}()
+	if err != nil {
+		return errorJSON("prepare_error", err.Error())
 	}
-	e.mu.Unlock()
 
 	evalOpts := []rego.EvalOption{}
 	if inputJson != nil {

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/go/builtins.go

@@ -62,12 +62,16 @@ func makeBuiltin(handle uint64, spec builtinSpec) func(*rego.Rego) {
 			if ret == nil {
 				return nil, fmt.Errorf("%s: callback returned NULL", spec.name)
 			}
-			// The host owns ret's buffer; copy it, do not free.
+			// The callback mallocs the response buffer and transfers ownership
+			// to us: copy the string out, then free with the C allocator via
+			// OpaFreeString. Nothing on the host side retains the pointer.
+			s := C.GoString(ret)
+			C.free(unsafe.Pointer(ret))
 			var envelope struct {
 				Result *json.RawMessage `json:"result"`
 				Error  *string          `json:"error"`
 			}
-			if err := json.Unmarshal([]byte(C.GoString(ret)), &envelope); err != nil {
+			if err := json.Unmarshal([]byte(s), &envelope); err != nil {
 				return nil, fmt.Errorf("%s: invalid callback response: %w", spec.name, err)
 			}
 			if envelope.Error != nil {

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/go/compile.go

@@ -8,6 +8,7 @@ import "C"
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 
 	"github.com/open-policy-agent/opa/v1/ast"
 	"github.com/open-policy-agent/opa/v1/rego"
@@ -23,6 +24,12 @@ import (
 //
 //export OpaCompileFilters
 func OpaCompileFilters(h C.ulonglong, query, inputJson, unknownsJson, target, dialect, mappingsJson, maskRule *C.char) *C.char {
+	return guard(func() *C.char {
+		return opaCompileFilters(h, query, inputJson, unknownsJson, target, dialect, mappingsJson, maskRule)
+	})
+}
+
+func opaCompileFilters(h C.ulonglong, query, inputJson, unknownsJson, target, dialect, mappingsJson, maskRule *C.char) *C.char {
 	e, err := getEngine(h)
 	if err != nil {
 		return errorJSON("invalid_handle", err.Error())
@@ -56,6 +63,9 @@ func OpaCompileFilters(h C.ulonglong, query, inputJson, unknownsJson, target, di
 		if err := json.Unmarshal([]byte(s), &mappings); err != nil {
 			return errorJSON("invalid_json", err.Error())
 		}
+		if err := validateMappings(mappings); err != nil {
+			return errorJSON("invalid_json", err.Error())
+		}
 		copts = append(copts, regocompile.Mappings(mappings))
 	}
 
@@ -67,18 +77,21 @@ func OpaCompileFilters(h C.ulonglong, query, inputJson, unknownsJson, target, di
 		copts = append(copts, regocompile.MaskRule(ref))
 	}
 
-	e.mu.Lock()
-	ropts := []func(*rego.Rego){
-		rego.Store(inmem.NewFromObject(e.data)),
-		rego.StrictBuiltinErrors(true),
-	}
-	for path, src := range e.modules {
-		ropts = append(ropts, rego.Module(path, src))
-	}
-	for _, b := range e.builtins {
-		ropts = append(ropts, makeBuiltin(uint64(h), b))
-	}
-	e.mu.Unlock()
+	ropts := func() []func(*rego.Rego) {
+		e.mu.Lock()
+		defer e.mu.Unlock()
+		ropts := []func(*rego.Rego){
+			rego.Store(inmem.NewFromObject(e.data)),
+			rego.StrictBuiltinErrors(true),
+		}
+		for path, src := range e.modules {
+			ropts = append(ropts, rego.Module(path, src))
+		}
+		for _, b := range e.builtins {
+			ropts = append(ropts, makeBuiltin(uint64(h), b))
+		}
+		return ropts
+	}()
 	copts = append(copts, regocompile.Rego(ropts...))
 
 	prepared, err := regocompile.New(copts...).Prepare(context.Background())
@@ -104,3 +117,28 @@ func OpaCompileFilters(h C.ulonglong, query, inputJson, unknownsJson, target, di
 	f := filters.For(tgt, dia)
 	return resultJSON(map[string]any{"query": f.Query, "masks": f.Masks})
 }
+
+// validateMappings enforces the shape OPA's translator assumes before the
+// mappings reach unchecked type assertions there: the top level maps table
+// (or unknown-short) names to objects; each entry maps column names to
+// strings, optionally alongside the string-valued "$self"/"$table" keys.
+// This returns an error instead of letting a malformed value panic and take
+// the whole host process down.
+func validateMappings(mappings map[string]any) error {
+	for table, tableMapping := range mappings {
+		tm, ok := tableMapping.(map[string]any)
+		if !ok {
+			return fmt.Errorf("mappings[%q]: table entry must be an object, got %T", table, tableMapping)
+		}
+		for column, columnMapping := range tm {
+			if _, ok := columnMapping.(string); ok {
+				continue
+			}
+			if column == "$self" || column == "$table" {
+				return fmt.Errorf("mappings[%q].%s: value must be a string, got %T", table, column, columnMapping)
+			}
+			return fmt.Errorf("mappings[%q].%q: column entry must be a string, got %T", table, column, columnMapping)
+		}
+	}
+	return nil
+}

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opa-golib-python-bindings"
-version = "0.4.0"
+version = "0.4.2"
 description = "Python bindings for the OPA (Open Policy Agent) Rego engine via a Go c-shared library"
 readme = "README.md"
 license = "Apache-2.0"

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/src/opa_bindings/_native.py

@@ -6,9 +6,10 @@ from pathlib import Path
 _LIB_PATH = Path(__file__).parent / "libopabridge.so"
 
 # char* (*opa_callback)(unsigned long long h, char* name, char* argsJson)
-# Return type is c_void_p so ctypes does not copy/free: the Python side keeps
-# the returned buffer alive until the callback is invoked again, and Go copies
-# it synchronously.
+# Return type is c_void_p so ctypes does not copy/free. The buffer is
+# malloc'd by the host with the C allocator and ownership transfers to the
+# Go side, which copies it and frees it with the same allocator; nothing on
+# the Python side retains the pointer.
 CALLBACK = ctypes.CFUNCTYPE(
     ctypes.c_void_p, ctypes.c_uint64, ctypes.c_char_p, ctypes.c_char_p
 )

{opa_golib_python_bindings-0.4.0 → opa_golib_python_bindings-0.4.2}/src/opa_bindings/engine.py

@@ -4,6 +4,7 @@ import ctypes
 import inspect
 import json
 import sys
+import threading
 
 from . import _native
 
@@ -21,6 +22,7 @@ class OpaUndefinedError(OpaError):
 
 
 _lib = None
+_libc = None
 
 
 def _get_lib():
@@ -30,20 +32,59 @@ def _get_lib():
     return _lib
 
 
+def _get_libc():
+    """Handle for libc's malloc: callback response buffers are owned by the
+    Go side, which frees them with the C allocator (see _dispatch)."""
+    global _libc
+    if _libc is None:
+        _libc = ctypes.CDLL(None)
+        _libc.malloc.restype = ctypes.c_void_p
+        _libc.malloc.argtypes = [ctypes.c_size_t]
+    return _libc
+
+
 class OpaEngine:
     """An embedded OPA policy engine instance.
 
     Policies are Rego modules added under a path, data is deep-merged JSON,
     and Python callables can be registered as custom Rego builtins.
+
+    Concurrency and resource notes:
+
+    - A single engine may be shared across threads: evaluations are
+      serialized by an internal re-entrant lock (which also allows a builtin
+      to evaluate on its own engine). Configuration calls (``add_policy``,
+      ``add_data``, ``register_function``) may interleave with evals from
+      other threads, as in the Go engine itself.
+    - Per-eval state (``last_coverage``, ``last_trace``, ``last_prints``)
+      reflects the most recently *completed* eval; under concurrent evals on
+      a shared engine these may interleave. Use one engine per thread, or
+      rely on return values instead of the ``last_*`` attributes, if that
+      matters.
+    - There are no built-in caps on memory or CPU: policy and data size,
+      number of engines (call ``close()`` to release one), and the number of
+      distinct queries evaluated are all bounded only by the process. Each
+      distinct query string is kept in a prepared-query cache on the engine
+      (invalidated by any configuration change), so applications that
+      evaluate unbounded attacker-shaped query strings grow memory without
+      bound — keep queries a fixed, application-controlled set.
     """
 
     def __init__(self):
         self._lib = _get_lib()
+        self._libc = _get_libc()
         self._handle = self._lib.OpaNew()
         self._functions = {}
-        # Buffers returned to Go must outlive the call; Go copies them
-        # synchronously, so keeping the latest buffer per builtin suffices.
-        self._callback_buffers = {}
+        # Serializes evals per engine so the per-eval callback buffer list
+        # below stays consistent even when multiple threads share an engine
+        # or a builtin re-enters eval on the same thread. A plain RLock: Go
+        # callbacks for this engine's builtins run on the calling thread while
+        # it holds the lock.
+        self._eval_lock = threading.RLock()
+        # Callback responses are malloc'd with the C allocator; Go frees them
+        # with OpaFreeString after copying (ownership transfer), so Python
+        # must NOT keep references. Buffers are only alive between _dispatch
+        # and the matching OpaFreeString, which the eval lock makes safe.
         self._trampoline = _native.CALLBACK(self._dispatch)
         #: Called as ``print_handler(message, location)`` for each Rego
         #: ``print(...)`` during evaluation; None writes them to stderr.
@@ -133,13 +174,20 @@ class OpaEngine:
         except Exception as e:  # never let an exception cross into Go
             response = {"error": repr(e)}
         try:
-            buf = ctypes.create_string_buffer(json.dumps(response).encode())
+            raw = json.dumps(response).encode()
         except Exception as e:
-            buf = ctypes.create_string_buffer(
-                json.dumps({"error": f"unserializable result: {e!r}"}).encode()
-            )
-        self._callback_buffers[name] = buf
-        return ctypes.addressof(buf)
+            raw = json.dumps({"error": f"unserializable result: {e!r}"}).encode()
+        # malloc with the C allocator: ownership of this buffer transfers to
+        # Go, which frees it with OpaFreeString (libc free) after copying.
+        # Nothing on the Python side retains the pointer. It must not be
+        # created with ctypes buffers — those use Python's allocator, which
+        # is not compatible with libc free.
+        buf = self._libc.malloc(len(raw) + 1)
+        if not buf:
+            return None  # Go reports "callback returned NULL"
+        ctypes.memmove(buf, raw, len(raw))
+        ctypes.memset(buf + len(raw), 0, 1)
+        return buf
 
     # -- public API ----------------------------------------------------
 
@@ -197,16 +245,17 @@ class OpaEngine:
         at each step, is stored in ``self.last_trace``.
         """
         self._check_open()
-        self._eval_reset()
-        rs = self._eval_result(
-            self._call(
-                self._lib.OpaEvalQuery,
-                query.encode(),
-                _encode_input(input),
-                int(coverage),
-                int(trace),
+        with self._eval_lock:
+            self._eval_reset()
+            rs = self._eval_result(
+                self._call(
+                    self._lib.OpaEvalQuery,
+                    query.encode(),
+                    _encode_input(input),
+                    int(coverage),
+                    int(trace),
+                )
             )
-        )
         if not rs:
             return []
         return [r.get("bindings", {}) for r in rs]
@@ -221,16 +270,17 @@ class OpaEngine:
         with ``trace=True`` the event trace is stored in ``self.last_trace``.
         """
         self._check_open()
-        self._eval_reset()
-        rs = self._eval_result(
-            self._call(
-                self._lib.OpaEvalDocument,
-                path.encode(),
-                _encode_input(input),
-                int(coverage),
-                int(trace),
+        with self._eval_lock:
+            self._eval_reset()
+            rs = self._eval_result(
+                self._call(
+                    self._lib.OpaEvalDocument,
+                    path.encode(),
+                    _encode_input(input),
+                    int(coverage),
+                    int(trace),
+                )
             )
-        )
         if not rs or not rs[0].get("expressions"):
             raise OpaUndefinedError(f"data.{path}" if path else "data")
         return rs[0]["expressions"][0]["value"]
@@ -279,16 +329,17 @@ class OpaEngine:
         is fine, as it resolves during partial evaluation.
         """
         self._check_open()
-        envelope = self._call(
-            self._lib.OpaCompileFilters,
-            query.encode(),
-            _encode_input(input),
-            json.dumps(list(unknowns)).encode(),
-            target.encode(),
-            dialect.encode(),
-            b"" if mappings is None else json.dumps(mappings).encode(),
-            (mask_rule or "").encode(),
-        )
+        with self._eval_lock:
+            envelope = self._call(
+                self._lib.OpaCompileFilters,
+                query.encode(),
+                _encode_input(input),
+                json.dumps(list(unknowns)).encode(),
+                target.encode(),
+                dialect.encode(),
+                b"" if mappings is None else json.dumps(mappings).encode(),
+                (mask_rule or "").encode(),
+            )
         return envelope.get("result")