wip: structure opa example

Author: alukach

README.md

@@ -178,9 +178,6 @@ The system supports generating CQL2 filters based on request context to provide
 > [!IMPORTANT]
 > The upstream STAC API must support the [STAC API Filter Extension](https://github.com/stac-api-extensions/filter/blob/main/README.md), including the [Features Filter](http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter) conformance class on to the Features resource (`/collections/{cid}/items`)[^37].
 
-> [!TIP]
-> Integration with external authorization systems (e.g. [Open Policy Agent](https://www.openpolicyagent.org/)) can be achieved by specifying an `ITEMS_FILTER` that points to a class/function that, once initialized, returns a [`cql2.Expr` object](https://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) when called with the request context.
-
 #### Filters
 
 If enabled, filters are intended to be applied to the following endpoints:
@@ -263,6 +260,99 @@ sequenceDiagram
     STAC API->>Client: Response
 ```
 
+#### Authoring Filter Generators
+
+The `ITEMS_FILTER_CLS` configuration option can be used to specify a class that will be used to generate a CQL2 filter for the request. The class must define a `__call__` method that accepts a single argument: a dictionary containing the request context; and returns a valid `cql2-text` expression (as a `str`) or `cql2-json` expression (as a `dict`).
+
+> [!TIP]
+> An example of an Open Policy Agent (OPA) integration is available in the [examples/opa](examples/opa) directory, runnable with `docker compose -f docker-compose.yaml -f examples/opa/docker-compose.yaml up`.
+
+##### Basic Filter Generator
+
+```py
+import dataclasses
+from typing import Any
+
+from cql2 import Expr
+
+
+@dataclasses.dataclass
+class ExampleFilter:
+    async def __call__(self, context: dict[str, Any]) -> str:
+        return "true"
+```
+
+> [!TIP]
+> Despite being referred to as a _class_, a filter generator could be written as a function.
+>
+>   <details>
+>
+>   <summary>Example</summary>
+>
+> ```py
+> from typing import Any
+>
+> from cql2 import Expr
+>
+>
+> def example_filter():
+>     def example_filter(context: dict[str, Any]) -> str | dict[str, Any]:
+>         return Expr("true")
+>     return example_filter
+> ```
+>
+> </details>
+
+##### Complex Filter Generator
+
+An example of a more complex filter generator where the filter is generated based on the response of an external API:
+
+```py
+import dataclasses
+from typing import Any
+
+from httpx import AsyncClient
+
+
+@dataclasses.dataclass
+class ApprovedCollectionsFilter:
+    api_url: str
+    kind: Literal["item", "collection"] = "item"
+    client: AsyncClient = dataclasses.field(init=False)
+
+    def __post_init__(self):
+        # We keep the client in the class instance to avoid creating a new client for
+        # each request, taking advantage of the client's connection pooling.
+        self.client = AsyncClient(base_url=self.api_url)
+
+    async def __call__(self, context: dict[str, Any]) -> dict[str, Any]:
+        # Lookup approved collections from an external API
+        token = context["req"]["headers"].get("Authorization")
+        approved_collections = await self.lookup(token)
+
+        # Build CQL2 filter
+        return {
+            "op": "a_containedby",
+            "args": [
+                {"property": "collection" if self.kind == "item" else "id"},
+                approved_collections
+            ],
+        }
+
+    async def lookup(self, token: Optional[str]) -> list[str]:
+        # Lookup approved collections from an external API
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        response = await self.client.get(
+            f"/get-approved-collections",
+            headers=headers,
+        )
+        response.raise_for_status()
+        return response.json()["collections"]
+```
+
+> [!TIP]
+> Filter generation runs for every relevant request. Consider memoizing external API calls to improve performance.
+
 [^21]: https://github.com/developmentseed/stac-auth-proxy/issues/21
 [^22]: https://github.com/developmentseed/stac-auth-proxy/issues/22
 [^23]: https://github.com/developmentseed/stac-auth-proxy/issues/23

examples/opa/.python-version

@@ -0,0 +1 @@
+3.13

examples/opa/Dockerfile

@@ -0,0 +1,5 @@
+FROM ghcr.io/developmentseed/stac-auth-proxy:latest
+
+ADD . /opa
+
+RUN pip install /opa

examples/opa/README.md

@@ -0,0 +1,11 @@
+# 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:
+
+```
+docker compose -f docker-compose.yaml -f examples/opa/docker-compose.yaml up
+```

examples/opa/docker-compose.yaml

@@ -0,0 +1,19 @@
+services:
+  proxy:
+    depends_on:
+      - stac
+    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: "[]"
+    env_file:
+      - path: .env
+        required: false
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./src:/app/src

examples/opa/opa_integration.py

@@ -0,0 +1,13 @@
+"""Integration with Open Policy Agent (OPA) to generate CQL2 filters for requests to a STAC API."""
+
+import dataclasses
+from typing import Any
+
+
+@dataclasses.dataclass
+class OpaIntegration:
+    """Integration with Open Policy Agent (OPA) to generate CQL2 filters for requests to a STAC API."""
+
+    async def __call__(self, context: dict[str, Any]) -> str:
+        """Generate a CQL2 filter for the request."""
+        return "(1=1)"

examples/opa/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "opa_integration"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []

pyproject.toml

@@ -53,3 +53,6 @@ dev = [
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "function"
 asyncio_mode = "auto"
+
+[tool.uv.workspace]
+members = ["examples/opa"]