feat: Buildout CQL2 filter tooling for reading Items (#17) + Refactor codebase into middleware (#20)

Author: alukach

.vscode/launch.json

@@ -16,6 +16,7 @@
       ],
       "jinja": true,
       "cwd": "${workspaceFolder}/src",
+      "justMyCode": false
     }
   ]
 }

README.md

@@ -9,7 +9,25 @@ STAC Auth Proxy is a proxy API that mediates between the client and and some int
 
 - 🔐 Selectively apply OIDC auth to some or all endpoints & methods
 - 📖 Augments [OpenAPI](https://swagger.io/specification/) with auth information, keeping auto-generated docs (e.g. [Swagger UI](https://swagger.io/tools/swagger-ui/)) accurate
-- 💂‍♀️ Custom policies enforce complex access controls, defined with [Common Expression Language (CEL)](https://cel.dev/)
+
+### CQL2 Filters
+
+| Method   | Endpoint                                       | Action | Filter | Strategy                                                                                                   |
+| -------- | ---------------------------------------------- | ------ | ------ | ---------------------------------------------------------------------------------------------------------- |
+| `POST`   | `/search`                                      | Read   | Item   | Append body with generated CQL2 query.                                                                     |
+| `GET`    | `/search`                                      | Read   | Item   | Append query params with generated CQL2 query.                                                             |
+| `GET`    | `/collections/{collection_id}/items`           | Read   | Item   | Append query params with generated CQL2 query.                                                             |
+| `POST`   | `/collections/{collection_id}/items`           | Create | Item   | Validate body with generated CQL2 query.                                                                   |
+| `PUT`    | `/collections/{collection_id}/items/{item_id}` | Update | Item   | Fetch STAC Item and validate CQL2 query; merge STAC Item with body and validate with generated CQL2 query. |
+| `DELETE` | `/collections/{collection_id}/items/{item_id}` | Delete | Item   | Fetch STAC Item and validate with CQL2 query.                                                              |
+
+#### Recipes
+
+Only return collections that are mentioned in a `collections` array encoded within the auth token.
+
+```
+"A_CONTAINEDBY(id, ('{{ token.collections | join(\"', '\") }}' ))"
+```
 
 ## Installation
 

pyproject.toml

@@ -8,19 +8,20 @@ classifiers = [
 dependencies = [
   "authlib>=1.3.2",
   "brotli>=1.1.0",
-  "cel-python>=0.1.5",
-  "eoapi-auth-utils>=0.4.0",
+  "cql2>=0.3.4",
   "fastapi>=0.115.5",
   "httpx>=0.28.0",
+  "jinja2>=3.1.4",
   "pydantic-settings>=2.6.1",
+  "pyjwt>=2.10.1",
   "uvicorn>=0.32.1",
 ]
 description = "STAC authentication proxy with FastAPI"
 keywords = ["STAC", "FastAPI", "Authentication", "Proxy"]
 license = {file = "LICENSE"}
 name = "stac-auth-proxy"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 version = "0.1.0"
 
 [tool.coverage.run]
@@ -42,6 +43,11 @@ requires = ["hatchling>=1.12.0"]
 dev = [
   "jwcrypto>=1.5.6",
   "pre-commit>=3.5.0",
+  "pytest-asyncio>=0.25.1",
   "pytest-cov>=5.0.0",
   "pytest>=8.3.3",
 ]
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"
+asyncio_mode = "auto"

src/stac_auth_proxy/app.py

@@ -8,12 +8,17 @@
 import logging
 from typing import Optional
 
-from eoapi.auth_utils import OpenIdConnectAuth
-from fastapi import Depends, FastAPI
+from fastapi import FastAPI
 
 from .config import Settings
-from .handlers import OpenApiSpecHandler, ReverseProxyHandler
-from .middleware import AddProcessTimeHeaderMiddleware
+from .handlers import ReverseProxyHandler
+from .middleware import (
+    AddProcessTimeHeaderMiddleware,
+    ApplyCql2FilterMiddleware,
+    BuildCql2FilterMiddleware,
+    EnforceAuthMiddleware,
+    OpenApiMiddleware,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -23,17 +28,35 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
     settings = settings or Settings()
 
     app = FastAPI(
-        openapi_url=None,
+        openapi_url=None,  # Disable OpenAPI schema endpoint, we want to serve upstream's schema
     )
+
     app.add_middleware(AddProcessTimeHeaderMiddleware)
 
-    auth_scheme = OpenIdConnectAuth(
-        openid_configuration_url=str(settings.oidc_discovery_url)
-    ).valid_token_dependency
+    if settings.openapi_spec_endpoint:
+        app.add_middleware(
+            OpenApiMiddleware,
+            openapi_spec_path=settings.openapi_spec_endpoint,
+            oidc_config_url=str(settings.oidc_discovery_url),
+            private_endpoints=settings.private_endpoints,
+            default_public=settings.default_public,
+        )
 
-    if settings.guard:
-        logger.info("Wrapping auth scheme")
-        auth_scheme = settings.guard(auth_scheme)
+    if settings.items_filter:
+        app.add_middleware(ApplyCql2FilterMiddleware)
+        app.add_middleware(
+            BuildCql2FilterMiddleware,
+            # collections_filter=settings.collections_filter,
+            items_filter=settings.items_filter(),
+        )
+
+    app.add_middleware(
+        EnforceAuthMiddleware,
+        public_endpoints=settings.public_endpoints,
+        private_endpoints=settings.private_endpoints,
+        default_public=settings.default_public,
+        oidc_config_url=settings.oidc_discovery_url,
+    )
 
     if settings.debug:
         app.add_api_route(
@@ -42,42 +65,12 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
             methods=["GET"],
         )
 
+    # Catchall for any endpoint
     proxy_handler = ReverseProxyHandler(upstream=str(settings.upstream_url))
-    openapi_handler = OpenApiSpecHandler(
-        proxy=proxy_handler, oidc_config_url=str(settings.oidc_discovery_url)
-    )
-
-    # Endpoints that are explicitely marked private
-    for path, methods in settings.private_endpoints.items():
-        app.add_api_route(
-            path,
-            (
-                proxy_handler.stream
-                if path != settings.openapi_spec_endpoint
-                else openapi_handler.dispatch
-            ),
-            methods=methods,
-            dependencies=[Depends(auth_scheme)],
-        )
-
-    # Endpoints that are explicitely marked as public
-    for path, methods in settings.public_endpoints.items():
-        app.add_api_route(
-            path,
-            (
-                proxy_handler.stream
-                if path != settings.openapi_spec_endpoint
-                else openapi_handler.dispatch
-            ),
-            methods=methods,
-        )
-
-    # Catchall for remainder of the endpoints
     app.add_api_route(
         "/{path:path}",
         proxy_handler.stream,
         methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
-        dependencies=([] if settings.default_public else [Depends(auth_scheme)]),
     )
 
     return app

src/stac_auth_proxy/config.py

@@ -3,7 +3,7 @@
 import importlib
 from typing import Optional, Sequence, TypeAlias
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from pydantic.networks import HttpUrl
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -14,15 +14,15 @@ class ClassInput(BaseModel):
     """Input model for dynamically loading a class or function."""
 
     cls: str
-    args: Optional[Sequence[str]] = []
-    kwargs: Optional[dict[str, str]] = {}
+    args: Sequence[str] = Field(default_factory=list)
+    kwargs: dict[str, str] = Field(default_factory=dict)
 
-    def __call__(self, token_dependency):
-        """Dynamically load a class and instantiate it with kwargs."""
+    def __call__(self):
+        """Dynamically load a class and instantiate it with args & kwargs."""
         module_path, class_name = self.cls.rsplit(".", 1)
         module = importlib.import_module(module_path)
         cls = getattr(module, class_name)
-        return cls(*self.args, **self.kwargs, token_dependency=token_dependency)
+        return cls(*self.args, **self.kwargs)
 
 
 class Settings(BaseSettings):
@@ -37,17 +37,26 @@ class Settings(BaseSettings):
     default_public: bool = False
     private_endpoints: EndpointMethods = {
         # https://github.com/stac-api-extensions/collection-transaction/blob/v1.0.0-beta.1/README.md#methods
-        "/collections": ["POST"],
-        "/collections/{collection_id}": ["PUT", "PATCH", "DELETE"],
+        r"^/collections$": ["POST"],
+        r"^/collections/([^/]+)$": ["PUT", "PATCH", "DELETE"],
         # https://github.com/stac-api-extensions/transaction/blob/v1.0.0-rc.3/README.md#methods
-        "/collections/{collection_id}/items": ["POST"],
-        "/collections/{collection_id}/items/{item_id}": ["PUT", "PATCH", "DELETE"],
+        r"^/collections/([^/]+)/items$": ["POST"],
+        r"^/collections/([^/]+)/items/([^/]+)$": ["PUT", "PATCH", "DELETE"],
         # https://stac-utils.github.io/stac-fastapi/api/stac_fastapi/extensions/third_party/bulk_transactions/#bulktransactionextension
-        "/collections/{collection_id}/bulk_items": ["POST"],
+        r"^/collections/([^/]+)/bulk_items$": ["POST"],
     }
-    public_endpoints: EndpointMethods = {"/api.html": ["GET"], "/api": ["GET"]}
+    public_endpoints: EndpointMethods = {r"^/api.html$": ["GET"], r"^/api$": ["GET"]}
     openapi_spec_endpoint: Optional[str] = None
 
-    model_config = SettingsConfigDict(env_prefix="STAC_AUTH_PROXY_")
+    # collections_filter: Optional[ClassInput] = None
+    # collections_filter_endpoints: Optional[EndpointMethods] = {
+    #     r"^/collections$": ["GET"],
+    #     r"^/collections$/([^/]+)": ["GET"],
+    # }
+    items_filter: Optional[ClassInput] = None
+    items_filter_endpoints: Optional[EndpointMethods] = {
+        r"^/search$": ["POST"],
+        r"^/collections/([^/]+)/items$": ["GET", "POST"],
+    }
 
-    guard: Optional[ClassInput] = None
+    model_config = SettingsConfigDict(env_prefix="STAC_AUTH_PROXY_")

src/stac_auth_proxy/filters/__init__.py

@@ -0,0 +1,5 @@
+"""CQL2 filter generators."""
+
+from .template import Template
+
+__all__ = ["Template"]

src/stac_auth_proxy/filters/template.py

@@ -0,0 +1,27 @@
+"""Generate CQL2 filter expressions via Jinja2 templating."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from cql2 import Expr
+from jinja2 import BaseLoader, Environment
+
+
+@dataclass
+class Template:
+    """Generate CQL2 filter expressions via Jinja2 templating."""
+
+    template_str: str
+    env: Environment = field(init=False)
+
+    def __post_init__(self):
+        """Initialize the Jinja2 environment."""
+        self.env = Environment(loader=BaseLoader).from_string(self.template_str)
+
+    async def __call__(self, context: dict[str, Any]) -> Expr:
+        """Render a CQL2 filter expression with the request and auth token."""
+        # TODO: How to handle the case where auth_token is null?
+        cql2_str = self.env.render(**context).strip()
+        cql2_expr = Expr(cql2_str)
+        cql2_expr.validate()
+        return cql2_expr

src/stac_auth_proxy/guards/__init__.py

@@ -1,6 +1,5 @@
 """Handlers to process requests."""
 
-from .open_api_spec import OpenApiSpecHandler
 from .reverse_proxy import ReverseProxyHandler
 
-__all__ = ["OpenApiSpecHandler", "ReverseProxyHandler"]
+__all__ = ["ReverseProxyHandler"]