feat: enhance CQL2 filter support for collections

- Added support for a collections filter in the configuration and middleware.
- Updated README to clarify content filtering based on request context.
- Refactored middleware to handle both items and collections filters.
- Improved error handling in filter application.
- Updated tests to include scenarios for collections filtering.

Author: alukach

README.md

@@ -10,7 +10,7 @@ STAC Auth Proxy is a proxy API that mediates between the client and your interna
 ## ✨Features✨
 
 - **🔐 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
+- **🛂 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 request context (e.g. user role)
 - **🤝 External Policy Integration:** Integrate with external systems (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
@@ -227,7 +227,7 @@ The system supports generating CQL2 filters based on request context to provide
 
 #### Filters
 
-If enabled, filters are intended to be applied to the following endpoints:
+If enabled, filters are applied to the following endpoints:
 
 - `GET /search`
   - **Supported:** ✅
@@ -250,12 +250,12 @@ If enabled, filters are intended to be applied to the following endpoints:
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Validate response against CQL2 query.
 - `GET /collections`
-  - **Supported:** ❌[^23]
+  - **Supported:** ✅
   - **Action:** Read Collection
   - **Applied Filter:** `COLLECTIONS_FILTER`
   - **Strategy:** Append query params with generated CQL2 query.
 - `GET /collections/{collection_id}`
-  - **Supported:** ❌[^23]
+  - **Supported:** ✅
   - **Action:** Read Collection
   - **Applied Filter:** `COLLECTIONS_FILTER`
   - **Strategy:** Validate response against CQL2 query.
@@ -411,6 +411,5 @@ class ApprovedCollectionsFilter:
 
 [^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
 [^30]: https://github.com/developmentseed/stac-auth-proxy/issues/30
 [^37]: https://github.com/developmentseed/stac-auth-proxy/issues/37

src/stac_auth_proxy/app.py

@@ -119,13 +119,16 @@ async def lifespan(app: FastAPI):
             auth_scheme_override=settings.openapi_auth_scheme_override,
         )
 
-    if settings.items_filter:
+    if settings.items_filter or settings.collections_filter:
         app.add_middleware(
             ApplyCql2FilterMiddleware,
         )
         app.add_middleware(
             BuildCql2FilterMiddleware,
-            items_filter=settings.items_filter(),
+            items_filter=settings.items_filter() if settings.items_filter else None,
+            collections_filter=(
+                settings.collections_filter() if settings.collections_filter else None
+            ),
         )
 
     app.add_middleware(

src/stac_auth_proxy/config.py

@@ -71,6 +71,7 @@ class Settings(BaseSettings):
 
     # Filters
     items_filter: Optional[ClassInput] = None
+    collections_filter: Optional[ClassInput] = None
 
     model_config = SettingsConfigDict(
         env_nested_delimiter="_",

src/stac_auth_proxy/middleware/ApplyCql2FilterMiddleware.py

@@ -51,7 +51,12 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             )
             return await req_body_handler(scope, receive, send)
 
-        if re.match(r"^/collections/([^/]+)/items/([^/]+)$", request.url.path):
+        # Handle single record requests (ie non-filterable endpoints)
+        single_record_endpoints = [
+            r"^/collections/([^/]+)/items/([^/]+)$",
+            r"^/collections/([^/]+)$",
+        ]
+        if any(re.match(expr, request.url.path) for expr in single_record_endpoints):
             res_body_validator = Cql2ResponseBodyValidator(
                 app=self.app,
                 cql2_filter=cql2_filter,
@@ -166,15 +171,19 @@ async def buffered_send(message: Message) -> None:
             logger.debug(
                 "Applying %s filter to %s", self.cql2_filter.to_text(), body_json
             )
-            if self.cql2_filter.matches(body_json):
-                await send(initial_message)
-                return await send(
-                    {
-                        "type": "http.response.body",
-                        "body": json.dumps(body_json).encode("utf-8"),
-                        "more_body": False,
-                    }
-                )
+            try:
+                if self.cql2_filter.matches(body_json):
+                    await send(initial_message)
+                    return await send(
+                        {
+                            "type": "http.response.body",
+                            "body": json.dumps(body_json).encode("utf-8"),
+                            "more_body": False,
+                        }
+                    )
+            except Exception as e:
+                logger.warning("Failed to apply filter: %s", e)
+
             return await _send_error_response(404, "Not found")
 
         return await self.app(scope, receive, buffered_send)

src/stac_auth_proxy/middleware/BuildCql2FilterMiddleware.py

@@ -25,7 +25,9 @@ class BuildCql2FilterMiddleware:
 
     # Filters
     collections_filter: Optional[Callable] = None
+    collections_filter_path: str = r"^/collections(/[^/]+)?$"
     items_filter: Optional[Callable] = None
+    items_filter_path: str = r"^(/collections/([^/]+)/items(/[^/]+)?$|/search$)"
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         """Build the CQL2 filter, place on the request state."""
@@ -65,8 +67,8 @@ def _get_filter(
     ) -> Optional[Callable[..., Awaitable[str | dict[str, Any]]]]:
         """Get the CQL2 filter builder for the given path."""
         endpoint_filters = [
-            (r"^/collections(/[^/]+)?$", self.collections_filter),
-            (r"^(/collections/([^/]+)/items(/[^/]+)?$|/search$)", self.items_filter),
+            (self.collections_filter_path, self.collections_filter),
+            (self.items_filter_path, self.items_filter),
         ]
         for expr, builder in endpoint_filters:
             if re.match(expr, path):

tests/conftest.py

@@ -207,6 +207,7 @@ def mock_env():
 @pytest.fixture
 async def mock_upstream() -> AsyncGenerator[MagicMock, None]:
     """Mock the HTTPX send method. Useful when we want to inspect the request is sent to upstream API."""
+    # NOTE: This fixture will interfere with the source_api_responses fixture
 
     async def store_body(request, **kwargs):
         """Exhaust and store the request body."""

tests/test_filters_jinja2.py

@@ -121,7 +121,7 @@
 )
 
 
-def _build_client(
+def _build_items_filter_client(
     *,
     src_api_server: str,
     template_expr: str,
@@ -162,7 +162,7 @@ async def test_search_post(
     token_builder,
 ):
     """Test that POST /search merges the upstream query with the templated filter."""
-    response = _build_client(
+    response = _build_items_filter_client(
         src_api_server=source_api_server,
         template_expr=filter_template_expr,
         is_authenticated=is_authenticated,
@@ -210,7 +210,7 @@ async def test_search_get(
     token_builder,
 ):
     """Test that GET /search merges the upstream query params with the templated filter."""
-    client = _build_client(
+    client = _build_items_filter_client(
         src_api_server=source_api_server,
         template_expr=filter_template_expr,
         is_authenticated=is_authenticated,
@@ -263,7 +263,7 @@ async def test_items_list(
     token_builder,
 ):
     """Test that GET /collections/foo/items merges query params with the templated filter."""
-    client = _build_client(
+    client = _build_items_filter_client(
         src_api_server=source_api_server,
         template_expr=filter_template_expr,
         is_authenticated=is_authenticated,
@@ -296,7 +296,7 @@ def test_item_get(
     source_api_server, is_authenticated, token_builder, source_api_responses
 ):
     """Test that GET /collections/foo/items/bar is rejected."""
-    client = _build_client(
+    client = _build_items_filter_client(
         src_api_server=source_api_server,
         template_expr="{{ '(properties.private = false)' if payload is none else true }}",
         is_authenticated=is_authenticated,
@@ -323,7 +323,7 @@ async def test_search_post_empty_body(
     token_builder,
 ):
     """Test that POST /search with empty body."""
-    client = _build_client(
+    client = _build_items_filter_client(
         src_api_server=source_api_server,
         template_expr="(properties.private = false)",
         is_authenticated=is_authenticated,
@@ -337,3 +337,145 @@ async def test_search_post_empty_body(
     )
 
     assert response.status_code == 200
+
+
+COLLECTIONS_FILTER_CASES = [
+    pytest.param(
+        "(properties.private = false)",
+        "(properties.private = false)",
+        "(properties.private = false)",
+        id="simple_collections_filter",
+    ),
+    pytest.param(
+        "{{ '(properties.private = false)' if payload is none else true }}",
+        "true",
+        "(properties.private = false)",
+        id="templated_collections_filter",
+    ),
+]
+
+COLLECTIONS_QUERIES = [
+    pytest.param(
+        {},
+        id="collections_no_filter",
+    ),
+    pytest.param(
+        {
+            "filter-lang": "cql2-text",
+            "filter": "(properties.private = true)",
+        },
+        id="collections_with_filter",
+    ),
+]
+
+
+def _build_collections_filter_client(
+    *,
+    src_api_server: str,
+    template_expr: str,
+    is_authenticated: bool,
+    token_builder,
+):
+    """Build a TestClient configured for either authenticated or anonymous usage."""
+    app = app_factory(
+        upstream_url=src_api_server,
+        collections_filter={
+            "cls": "stac_auth_proxy.filters:Template",
+            "args": [template_expr.strip()],
+        },
+        default_public=True,
+    )
+    headers = (
+        {"Authorization": f"Bearer {token_builder({'sub': 'test-user'})}"}
+        if is_authenticated
+        else {}
+    )
+    return TestClient(app, headers=headers)
+
+
+@pytest.mark.parametrize(
+    "filter_template_expr, expected_auth_filter, expected_anon_filter",
+    COLLECTIONS_FILTER_CASES,
+)
+@pytest.mark.parametrize("is_authenticated", [True, False], ids=["auth", "anon"])
+@pytest.mark.parametrize("input_query", COLLECTIONS_QUERIES)
+async def test_collections_list(
+    mock_upstream,
+    source_api_server,
+    filter_template_expr,
+    expected_auth_filter,
+    expected_anon_filter,
+    is_authenticated,
+    input_query,
+    token_builder,
+):
+    """Test that GET /collections merges query params with the templated filter."""
+    client = _build_collections_filter_client(
+        src_api_server=source_api_server,
+        template_expr=filter_template_expr,
+        is_authenticated=is_authenticated,
+        token_builder=token_builder,
+    )
+    response = client.get("/collections", params=input_query)
+    response.raise_for_status()
+
+    # For GET collections, we expect an empty body and appended querystring
+    proxied_request = await get_upstream_request(mock_upstream)
+    assert proxied_request.body == ""
+
+    # Determine the expected combined filter
+    proxy_filter = cql2.Expr(
+        expected_auth_filter if is_authenticated else expected_anon_filter
+    )
+    input_filter = input_query.get("filter")
+    if input_filter:
+        proxy_filter += cql2.Expr(input_filter)
+
+    filter_lang = input_query.get("filter-lang", "cql2-text")
+    expected_output = {
+        **input_query,
+        "filter": (
+            proxy_filter.to_text()
+            if filter_lang == "cql2-text"
+            else proxy_filter.to_json()
+        ),
+        "filter-lang": filter_lang,
+    }
+    assert (
+        proxied_request.query_params == expected_output
+    ), "Collections query should combine filter expressions."
+
+
+@pytest.mark.parametrize(
+    "filter_template_expr, expected_auth_filter, expected_anon_filter",
+    COLLECTIONS_FILTER_CASES,
+)
+@pytest.mark.parametrize("is_authenticated", [True, False], ids=["auth", "anon"])
+async def test_collection_get(
+    source_api_server,
+    filter_template_expr,
+    expected_auth_filter,
+    expected_anon_filter,
+    is_authenticated,
+    token_builder,
+    source_api_responses,
+):
+    """Test that GET /collections/{collection_id} applies the templated filter."""
+    client = _build_collections_filter_client(
+        src_api_server=source_api_server,
+        template_expr=filter_template_expr,
+        is_authenticated=is_authenticated,
+        token_builder=token_builder,
+    )
+    response_body = {
+        "id": "foo",
+        "properties": {"private": True},
+    }
+    source_api_responses["/collections/{collection_id}"]["GET"] = response_body
+    response = client.get("/collections/foo")
+
+    # Expected applied filter
+    proxy_filter = cql2.Expr(
+        expected_auth_filter if is_authenticated else expected_anon_filter
+    )
+    assert response.status_code == 200 if proxy_filter.matches(response_body) else 404