Merge branch 'main' into authentication-ext/asset-signing

Author: alukach

Dockerfile

@@ -1,17 +1,25 @@
+# https://github.com/astral-sh/uv-docker-example/blob/c16a61fb3e6ab568ac58d94b73a7d79594a5d570/Dockerfile
 FROM python:3.13-slim
 
-EXPOSE 8000
-
 WORKDIR /app
 
-RUN apt-get update && apt-get install -y gcc libpq-dev
+ENV PATH="/app/.venv/bin:$PATH"
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+ENV UV_PROJECT_ENVIRONMENT=/usr/local
 
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
-COPY . .
-
-ENV PYTHONUNBUFFERED=1
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+  --mount=type=bind,source=uv.lock,target=uv.lock \
+  --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+  uv sync --frozen --no-install-project --no-dev
 
-RUN uv sync --no-dev --locked
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+  uv sync --frozen --no-dev
 
-CMD ["uv", "run", "--locked", "--no-dev", "python", "-m", "stac_auth_proxy"]
+CMD ["python", "-m", "stac_auth_proxy"]

README.md

@@ -33,7 +33,7 @@ pip install -e .
 ```
 
 > [!NOTE]
-> This project will be available on PyPi in the near future ([#30](https://github.com/developmentseed/stac-auth-proxy/issues/30)).
+> This project will be available on PyPi in the near future[^30].
 
 ### Running
 
@@ -43,8 +43,8 @@ The simplest way to run the project is by invoking the application via Docker:
 docker run \
   -it --rm \
   -p 8000:8000 \
-  -e UPSTREAM_URL=https://google.com \
-  -e OIDC_DISCOVERY_URL=https://auth.openveda.cloud/realms/veda/.well-known/openid-configuration \
+  -e UPSTREAM_URL=https://my-stac-api \
+  -e OIDC_DISCOVERY_URL=https://my-auth-server/.well-known/openid-configuration \
   ghcr.io/developmentseed/stac-auth-proxy:latest
 ```
 
@@ -71,6 +71,10 @@ The application is configurable via environment variables.
     - **Type:** boolean
     - **Required:** No, defaults to `true`
     - **Example:** `false`, `1`, `True`
+  - **`CHECK_CONFORMANCE`**, ensure upstream API conforms to required conformance classes before starting proxy
+    - **Type:** boolean
+    - **Required:** No, defaults to `true`
+    - **Example:** `false`, `1`, `True`
   - **`HEALTHZ_PREFIX`**, path prefix for health check endpoints
     - **Type:** string
     - **Required:** No, defaults to `/healthz`
@@ -105,26 +109,26 @@ The application is configurable via environment variables.
     - **Required:** No, defaults to the following:
       ```json
       {
-        r"^/api.html$": ["GET"],
-        r"^/api$": ["GET"],
-        r"^/docs/oauth2-redirect": ["GET"],
-        r"^/healthz": ["GET"],
+        "^/api.html$": ["GET"],
+        "^/api$": ["GET"],
+        "^/docs/oauth2-redirect": ["GET"],
+        "^/healthz": ["GET"]
       }
       ```
   - **`OPENAPI_SPEC_ENDPOINT`**, path of OpenAPI specification, used for augmenting spec response with auth configuration
     - **Type:** string or null
     - **Required:** No, defaults to `null` (disabled)
     - **Example:** `/api`
 - Filtering
-  - **`ITEMS_FILTER_CLS`**, [cql2 expression](https://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) generator for item-level filtering
+  - **`ITEMS_FILTER_CLS`**, CQL2 expression generator for item-level filtering
     - **Type:** JSON object with class configuration
     - **Required:** No, defaults to `null` (disabled)
     - **Example:** `my_package.filters:OrganizationFilter`
-  - **`ITEMS_FILTER_ARGS`**, [cql2 expression](https://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) generator for item-level filtering
+  - **`ITEMS_FILTER_ARGS`**, Positional arguments for CQL2 expression generator
     - **Type:** List of positional arguments used to initialize the class
     - **Required:** No, defaults to `[]`
     - **Example:**: `["org1"]`
-  - **`ITEMS_FILTER_KWARGS`**, [cql2 expression](https://developmentseed.org/cql2-rs/latest/python/#cql2.Expr) generator for item-level filtering
+  - **`ITEMS_FILTER_KWARGS`**, Keyword arguments for CQL2 expression generator
     - **Type:** Dictionary of keyword arguments used to initialize the class
     - **Required:** No, defaults to `{}`
     - **Example:** `{ "field_name": "properties.organization" }`
@@ -172,7 +176,7 @@ The majority of the proxy's functionality occurs within a chain of middlewares.
 The system supports generating CQL2 filters based on request context to provide row-level content filtering. These CQL2 filters are then set on outgoing requests prior to the upstream API.
 
 > [!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](https://github.com/developmentseed/stac-auth-proxy/issues/37).
+> 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.
@@ -191,53 +195,58 @@ If enabled, filters are intended to be applied to the following endpoints:
   - **Action:** Read Item
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Append body with generated CQL2 query.
-- `GET /collections/{collection_id}`
-  - **Supported:** ❌ ([#23](https://github.com/developmentseed/stac-auth-proxy/issues/23))
-  - **Action:** Read Collection
-  - **Applied Filter:** `COLLECTIONS_FILTER`
-  - **Strategy:** Append query params with generated CQL2 query.
 - `GET /collections/{collection_id}/items`
   - **Supported:** ✅
   - **Action:** Read Item
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Append query params with generated CQL2 query.
 - `GET /collections/{collection_id}/items/{item_id}`
-  - **Supported:** ❌ ([#25](https://github.com/developmentseed/stac-auth-proxy/issues/25))
+  - **Supported:** ✅
   - **Action:** Read Item
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Validate response against CQL2 query.
+- `GET /collections`
+  - **Supported:** ❌[^23]
+  - **Action:** Read Collection
+  - **Applied Filter:** `COLLECTIONS_FILTER`
+  - **Strategy:** Append query params with generated CQL2 query.
+- `GET /collections/{collection_id}`
+  - **Supported:** ❌[^23]
+  - **Action:** Read Collection
+  - **Applied Filter:** `COLLECTIONS_FILTER`
+  - **Strategy:** Validate response against CQL2 query.
 - `POST /collections/`
-  - **Supported:** ❌ ([#22](https://github.com/developmentseed/stac-auth-proxy/issues/22))
+  - **Supported:** ❌[^22]
   - **Action:** Create Collection
   - **Applied Filter:** `COLLECTIONS_FILTER`
   - **Strategy:** Validate body with generated CQL2 query.
 - `PUT /collections/{collection_id}}`
-  - **Supported:** ❌ ([#22](https://github.com/developmentseed/stac-auth-proxy/issues/22))
+  - **Supported:** ❌[^22]
   - **Action:** Update Collection
   - **Applied Filter:** `COLLECTIONS_FILTER`
   - **Strategy:** Fetch Collection and validate CQL2 query; merge Item with body and validate with generated CQL2 query.
 - `DELETE /collections/{collection_id}`
-  - **Supported:** ❌ ([#22](https://github.com/developmentseed/stac-auth-proxy/issues/22))
+  - **Supported:** ❌[^22]
   - **Action:** Delete Collection
   - **Applied Filter:** `COLLECTIONS_FILTER`
   - **Strategy:** Fetch Collectiion and validate with CQL2 query.
 - `POST /collections/{collection_id}/items`
-  - **Supported:** ❌ ([#21](https://github.com/developmentseed/stac-auth-proxy/issues/21))
+  - **Supported:** ❌[^21]
   - **Action:** Create Item
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Validate body with generated CQL2 query.
 - `PUT /collections/{collection_id}/items/{item_id}`
-  - **Supported:** ❌ ([#21](https://github.com/developmentseed/stac-auth-proxy/issues/21))
+  - **Supported:** ❌[^21]
   - **Action:** Update Item
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Fetch Item and validate CQL2 query; merge Item with body and validate with generated CQL2 query.
 - `DELETE /collections/{collection_id}/items/{item_id}`
-  - **Supported:** ❌ ([#21](https://github.com/developmentseed/stac-auth-proxy/issues/21))
+  - **Supported:** ❌[^21]
   - **Action:** Delete Item
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Fetch Item and validate with CQL2 query.
 - `POST /collections/{collection_id}/bulk_items`
-  - **Supported:** ❌ ([#21](https://github.com/developmentseed/stac-auth-proxy/issues/21))
+  - **Supported:** ❌[^21]
   - **Action:** Create Items
   - **Applied Filter:** `ITEMS_FILTER`
   - **Strategy:** Validate items in body with generated CQL2 query.
@@ -253,3 +262,9 @@ sequenceDiagram
     Proxy->>STAC API: GET /collection?filter=(collection=landsat)
     STAC API->>Client: Response
 ```
+
+[^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

pyproject.toml

@@ -8,7 +8,7 @@ classifiers = [
 dependencies = [
   "boto3>=1.37.16",
   "brotli>=1.1.0",
-  "cql2>=0.3.5",
+  "cql2>=0.3.6",
   "fastapi>=0.115.5",
   "httpx[http2]>=0.28.0",
   "jinja2>=3.1.4",

src/stac_auth_proxy/app.py

@@ -22,7 +22,7 @@
     EnforceAuthMiddleware,
     OpenApiMiddleware,
 )
-from .utils.lifespan import check_server_health
+from .utils.lifespan import check_conformance, check_server_health
 
 logger = logging.getLogger(__name__)
 
@@ -41,8 +41,26 @@ async def lifespan(app: FastAPI):
 
         # Wait for upstream servers to become available
         if settings.wait_for_upstream:
-            for url in [settings.upstream_url, settings.oidc_discovery_internal_url]:
+            logger.info("Running upstream server health checks...")
+            urls = [settings.upstream_url, settings.oidc_discovery_internal_url]
+            for url in urls:
                 await check_server_health(url=url)
+            logger.info(
+                "Upstream servers are healthy:\n%s",
+                "\n".join([f" - {url}" for url in urls]),
+            )
+
+        # Log all middleware connected to the app
+        logger.info(
+            "Connected middleware:\n%s",
+            "\n".join([f" - {m.cls.__name__}" for m in app.user_middleware]),
+        )
+
+        if settings.check_conformance:
+            await check_conformance(
+                app.user_middleware,
+                str(settings.upstream_url),
+            )
 
         yield
 
@@ -107,19 +125,19 @@ async def lifespan(app: FastAPI):
         )
 
     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_internal_url,
+        CompressionMiddleware,
     )
 
     app.add_middleware(
-        CompressionMiddleware,
+        AddProcessTimeHeaderMiddleware,
     )
 
     app.add_middleware(
-        AddProcessTimeHeaderMiddleware,
+        EnforceAuthMiddleware,
+        public_endpoints=settings.public_endpoints,
+        private_endpoints=settings.private_endpoints,
+        default_public=settings.default_public,
+        oidc_config_url=settings.oidc_discovery_internal_url,
     )
 
     return app

src/stac_auth_proxy/config.py

@@ -39,6 +39,7 @@ class Settings(BaseSettings):
     oidc_discovery_internal_url: HttpUrl
 
     wait_for_upstream: bool = True
+    check_conformance: bool = True
 
     # Endpoints
     healthz_prefix: str = Field(pattern=_PREFIX_PATTERN, default="/healthz")

src/stac_auth_proxy/filters/template.py

@@ -3,7 +3,6 @@
 from dataclasses import dataclass, field
 from typing import Any
 
-from cql2 import Expr
 from jinja2 import BaseLoader, Environment
 
 
@@ -18,10 +17,6 @@ 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:
+    async def __call__(self, context: dict[str, Any]) -> str:
         """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
+        return self.env.render(**context).strip()