in progress

alukach · alukach · commit db03850df412 · 2025-04-06T21:23:00.000-07:00
diff --git a/README.md b/README.md
@@ -9,11 +9,12 @@ STAC Auth Proxy is a proxy API that mediates between the client and your interna
 
 ## ✨Features✨
 
-- 🔐 Authentication: Selectively apply [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) auth\*n token validation & optional scope requirements to some or all endpoints & methods
-- 🛂 Content Filtering: Apply CQL2 filters to client requests, utilizing the [Filter Extension](https://github.com/stac-api-extensions/filter?tab=readme-ov-file) to filter API content based on user context
-- 🧩 Authentication Extension: Integrate the [Authentication Extension](https://github.com/stac-extensions/authentication) into API responses
-- 📘 OpenAPI Augmentation: Update API's [OpenAPI document](https://swagger.io/specification/) with security requirements, keeping auto-generated docs/UIs accurate (e.g. [Swagger UI](https://swagger.io/tools/swagger-ui/))
-- 🗜️ Response compression: Compress API responses via [`starlette-cramjam`](https://github.com/developmentseed/starlette-cramjam/)
+- **🔐 Authentication:** Apply [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) token validation and optional scope checks to specified endpoints and methods
+- **🛂 Content Filtering:** Use CQL2 filters via the [Filter Extension](https://github.com/stac-api-extensions/filter?tab=readme-ov-file) to tailor API responses based on user context
+- **🤝 External Policy Integration:** Integrate with externalsystems (e.g. [Open Policy Agent (OPA)](https://www.openpolicyagent.org/)) to generate CQL2 filters dynamically from policy decisions
+- **🧩 Authentication Extension:** Add the [Authentication Extension](https://github.com/stac-extensions/authentication) to API responses to expose auth-related metadata
+- **📘 OpenAPI Augmentation:** Enhance the [OpenAPI spec](https://swagger.io/specification/) with security details to keep auto-generated docs and UIs (e.g., [Swagger UI](https://swagger.io/tools/swagger-ui/)) accurate
+- **🗜️ Response Compression:** Optimize response sizes using [`starlette-cramjam`](https://github.com/developmentseed/starlette-cramjam/)
 
 ## Usage
 
diff --git a/examples/custom-integration/.python-version b/examples/custom-integration/.python-version
diff --git a/examples/custom-integration/Dockerfile b/examples/custom-integration/Dockerfile
diff --git a/examples/custom-integration/README.md b/examples/custom-integration/README.md
@@ -0,0 +1,27 @@
+# Open Policy Agent (OPA) Integration
+
+This example demonstrates how to integrate with an Open Policy Agent (OPA) to authorize requests to a STAC API.
+
+## Running the Example
+
+From the root directory, run:
+
+```sh
+docker compose -f docker-compose.yaml -f examples/opa/docker-compose.yaml up
+```
+
+## Testing OPA
+
+```sh
+▶ curl -X POST "http://localhost:8181/v1/data/stac/cql2" \
+  -H "Content-Type: application/json" \
+  -d '{"input":{"payload": null}}'
+{"result":"private = true"}
+```
+
+```sh
+▶ curl -X POST "http://localhost:8181/v1/data/stac/cql2" \
+  -H "Content-Type: application/json" \
+  -d '{"input":{"payload": {"sub": "user1"}}}'
+{"result":"1=1"}
+```
diff --git a/examples/custom-integration/docker-compose.yaml b/examples/custom-integration/docker-compose.yaml
@@ -0,0 +1,30 @@
+services:
+  proxy:
+    depends_on:
+      - stac
+      - opa
+    build:
+      context: examples/opa
+    # environment:
+    #   UPSTREAM_URL: ${UPSTREAM_URL:-http://stac:8001}
+    #   OIDC_DISCOVERY_URL: ${OIDC_DISCOVERY_URL:-http://localhost:8888/.well-known/openid-configuration}
+    #   OIDC_DISCOVERY_INTERNAL_URL: ${OIDC_DISCOVERY_INTERNAL_URL:-http://oidc:8888/.well-known/openid-configuration}
+    #   ITEMS_FILTER_CLS: opa_integration:OpaIntegration
+    #   ITEMS_FILTER_ARGS: '["http://opa:8181", "stac/cql2"]'
+    env_file:
+      - path: .env
+        required: false
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./src:/app/src
+
+  opa:
+    image: openpolicyagent/opa:latest
+    command: "run --server --addr=:8181 --watch /policies"
+    ports:
+      - "8181:8181"
+    volumes:
+      - ./examples/opa/policies:/policies
+    depends_on:
+      - stac
diff --git a/examples/custom-integration/policies/stac/policy.rego b/examples/custom-integration/policies/stac/policy.rego
@@ -0,0 +1,7 @@
+package stac
+
+default cql2 := "private = true"
+
+cql2 := "1=1" if {
+	input.payload.sub != null
+}
diff --git a/examples/custom-integration/pyproject.toml b/examples/custom-integration/pyproject.toml
@@ -1,5 +1,5 @@
 [project]
-name = "opa_integration"
+name = "custom_integration"
 version = "0.1.0"
 description = "Add your description here"
 readme = "README.md"
diff --git a/examples/opa/docker-compose.yaml b/examples/opa/docker-compose.yaml
@@ -1,23 +1,8 @@
 services:
   proxy:
-    depends_on:
-      - stac
-      - opa
-    build:
-      context: examples/opa
     environment:
-      UPSTREAM_URL: ${UPSTREAM_URL:-http://stac:8001}
-      OIDC_DISCOVERY_URL: ${OIDC_DISCOVERY_URL:-http://localhost:8888/.well-known/openid-configuration}
-      OIDC_DISCOVERY_INTERNAL_URL: ${OIDC_DISCOVERY_INTERNAL_URL:-http://oidc:8888/.well-known/openid-configuration}
-      ITEMS_FILTER_CLS: opa_integration:OpaIntegration
+      ITEMS_FILTER_CLS: stac_auth_proxy.filters:Opa
       ITEMS_FILTER_ARGS: '["http://opa:8181", "stac/cql2"]'
-    env_file:
-      - path: .env
-        required: false
-    ports:
-      - "8000:8000"
-    volumes:
-      - ./src:/app/src
 
   opa:
     image: openpolicyagent/opa:latest
@@ -26,5 +11,3 @@ services:
       - "8181:8181"
     volumes:
       - ./examples/opa/policies:/policies
-    depends_on:
-      - stac
diff --git a/examples/opa/policies/stac/policy.rego b/examples/opa/policies/stac/policy.rego
@@ -1,6 +1,6 @@
 package stac
 
-default cql2 := "private = true"
+default cql2 := "\"naip:year\" = 2021"
 
 cql2 := "1=1" if {
 	input.payload.sub != null
diff --git a/examples/opa/src/opa_integration.py b/examples/opa/src/opa_integration.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -55,6 +55,3 @@ dev = [
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "function"
 asyncio_mode = "auto"
-
-[tool.uv.workspace]
-members = ["examples/opa"]
diff --git a/src/stac_auth_proxy/filters/__init__.py b/src/stac_auth_proxy/filters/__init__.py
@@ -1,5 +1,9 @@
 """CQL2 filter generators."""
 
+from .opa import Opa
 from .template import Template
 
-__all__ = ["Template"]
+__all__ = [
+    "Opa",
+    "Template",
+]
diff --git a/src/stac_auth_proxy/filters/opa.py b/src/stac_auth_proxy/filters/opa.py
@@ -0,0 +1,38 @@
+"""Integration with Open Policy Agent (OPA) to generate CQL2 filters for requests to a STAC API."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from ..utils.filters import MemoryCache
+
+
+@dataclass
+class Opa:
+    """Call Open Policy Agent (OPA) to generate CQL2 filters from request context."""
+
+    host: str
+    decision: str
+
+    client: httpx.AsyncClient = field(init=False)
+    cache: MemoryCache = field(init=False)
+    cache_key: str = "req.headers.authorization"
+    cache_ttl: float = 5.0
+
+    def __post_init__(self):
+        """Initialize the client."""
+        self.client = httpx.AsyncClient(base_url=self.host)
+        self.cache = MemoryCache(key=self.cache_key, ttl=self.cache_ttl)
+
+    async def __call__(self, context: dict[str, Any]) -> str:
+        """Generate a CQL2 filter for the request."""
+        if cached_result := self.cache.get(context):
+            return cached_result
+        response = await self.client.post(
+            f"/v1/data/{self.decision}",
+            json={"input": context},
+        )
+        result = response.raise_for_status().json()["result"]
+        self.cache.set(context, result)
+        return result
diff --git a/src/stac_auth_proxy/utils/filters.py b/src/stac_auth_proxy/utils/filters.py
@@ -1,11 +1,16 @@
 """Utility functions."""
 
 import json
-from typing import Optional
+import logging
+from dataclasses import dataclass, field
+from time import time
+from typing import Any, Optional
 from urllib.parse import parse_qs
 
 from cql2 import Expr
 
+logger = logging.getLogger(__name__)
+
 
 def append_qs_filter(qs: str, filter: Expr, filter_lang: Optional[str] = None) -> bytes:
     """Insert a filter expression into a query string. If a filter already exists, combine them."""
@@ -42,3 +47,72 @@ def dict_to_query_string(params: dict) -> str:
             val = json.dumps(val, separators=(",", ":"))
         parts.append(f"{key}={val}")
     return "&".join(parts)
+
+
+@dataclass
+class MemoryCache:
+    """Cache results of a method call for a given key."""
+
+    key: str
+    ttl: float = 5.0
+    cache: dict[tuple[Any], tuple[Any, float]] = field(default_factory=dict)
+
+    def get(self, ctx: Any) -> Any:
+        """Get a value from the cache."""
+        key = self.get_value_by_path(ctx, self.key)
+        if key in self.cache:
+            result, timestamp = self.cache[key]
+            age = time() - timestamp
+            if age <= self.ttl:
+                logger.debug(
+                    "%r in cache, returning cached result",
+                    key if len(str(key)) < 10 else f"{str(key)[:9]}...",
+                )
+                return result
+            logger.debug(
+                "%r in cache, but expired.",
+                key if len(str(key)) < 10 else f"{key[:9]}...",
+            )
+        else:
+            logger.debug(
+                "%r not in cache, calling function",
+                key if len(str(key)) < 10 else f"{key[:9]}...",
+            )
+        return None
+
+    def set(self, ctx: Any, value: Any):
+        """Set a value in the cache."""
+        key = self.get_value_by_path(ctx, self.key)
+        self.cache[key] = (value, time())
+        self.prune()
+
+    def prune(self):
+        """Prune the cache of expired items."""
+        self.cache = {
+            k: (v, time_entered)
+            for k, (v, time_entered) in self.cache.items()
+            if time_entered > (time() - self.ttl)
+        }
+
+    @staticmethod
+    def get_value_by_path(obj: dict, path: str, default: Any = None) -> Any:
+        """
+        Get a value from a dictionary using dot notation.
+
+        Args:
+            obj: The dictionary to search in
+            path: The dot notation path (e.g. "payload.sub")
+            default: Default value to return if path doesn't exist
+
+        Returns
+        -------
+            The value at the specified path or default if path doesn't exist
+        """
+        try:
+            for key in path.split("."):
+                if obj is None:
+                    return default
+                obj = obj.get(key, None)
+            return obj
+        except (AttributeError, KeyError, TypeError):
+            return default
