feat: Add header filtering for collections and geometry, apply geometry filters to single item access

Author: Andrzej Pijanowski

README.md

@@ -126,6 +126,7 @@ This project is built on the following technologies: STAC, stac-fastapi, FastAPI
   - [Managing Elasticsearch Indices](#managing-elasticsearch-indices)
     - [Snapshots](#snapshots)
     - [Reindexing](#reindexing)
+  - [Header Filtering](#header-filtering)
   - [Auth](#auth)
   - [Aggregation](#aggregation)
   - [Rate Limiting](#rate-limiting)
@@ -1015,6 +1016,39 @@ pip install stac-fastapi-elasticsearch[redis]
   - This makes the modified Items with lowercase identifiers visible to users accessing my-collection in the STAC API
   - Using aliases allows you to switch between different index versions without changing the API endpoint
 
+## Header Filtering
+
+SFEOS supports filtering API responses based on HTTP headers. This enables upstream proxies or gateways to restrict access to specific collections and geographic areas.
+
+### Headers
+
+| Header | Format | Description |
+|--------|--------|-------------|
+| `X-Filter-Collections` | Comma-separated IDs | Restricts access to specified collections only |
+| `X-Filter-Geometry` | GeoJSON geometry | Restricts access to items within the specified geometry |
+
+### Affected Endpoints
+
+| Endpoint | Collection Filter | Geometry Filter |
+|----------|:-----------------:|:---------------:|
+| `GET /collections` | ✅ | - |
+| `GET /collections/{id}` | ✅ (404 if denied) | - |
+| `GET /collections/{id}/items` | ✅ | ✅ |
+| `GET /collections/{id}/items/{id}` | ✅ (404 if denied) | ✅* (404 if denied) |
+| `GET/POST /search` | ✅ | ✅ |
+
+*Requires optional `shapely` dependency.
+
+### Optional Dependency
+
+For geometry filtering on single item endpoints (`/collections/{id}/items/{id}`), install with the `geo` extra:
+
+```bash
+pip install stac-fastapi-core[geo]
+```
+
+Without this dependency, geometry filtering on single items is skipped with a warning.
+
 ## Auth
 
 - **Overview**: Authentication is an optional feature that can be enabled through Route Dependencies.

stac_fastapi/core/pyproject.toml

@@ -49,6 +49,9 @@ redis = [
     "redis~=6.4.0",
     "retry~=0.9.2",
 ]
+geo = [
+    "shapely>=2.0.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch"

stac_fastapi/core/stac_fastapi/core/core.py

@@ -693,7 +693,19 @@ async def get_item(
         item = await self.database.get_one_item(
             item_id=item_id, collection_id=collection_id
         )
-        return self.item_serializer.db_to_stac(item, base_url)
+        stac_item = self.item_serializer.db_to_stac(item, base_url)
+
+        # Check if item geometry intersects with allowed geometry filter
+        header_geometry = parse_filter_geometry(request)
+        if header_geometry is not None:
+            item_geometry = stac_item.get("geometry")
+            if item_geometry:
+                from stac_fastapi.core.header_filters import geometry_intersects_filter
+
+                if not geometry_intersects_filter(item_geometry, header_geometry):
+                    raise HTTPException(status_code=404, detail="Item not found")
+
+        return stac_item
 
     async def get_search(
         self,

stac_fastapi/core/stac_fastapi/core/header_filters.py

@@ -76,3 +76,39 @@ def parse_filter_geometry(request: Request) -> Optional[Dict[str, Any]]:
     except json.JSONDecodeError as e:
         logger.warning(f"Failed to parse geometry header: {e}")
         return None
+
+
+def geometry_intersects_filter(
+    item_geometry: Dict[str, Any], filter_geometry: Dict[str, Any]
+) -> bool:
+    """Check if item geometry intersects with the filter geometry.
+
+    Args:
+        item_geometry: GeoJSON geometry dict from the item.
+        filter_geometry: GeoJSON geometry dict from header filter.
+
+    Returns:
+        True if geometries intersect (or if shapely not available), False otherwise.
+
+    Note:
+        Requires shapely to be installed. If shapely is not available,
+        this function returns True (allows access) to avoid breaking
+        deployments without shapely.
+    """
+    try:
+        from shapely.geometry import shape
+    except ImportError:
+        logger.warning(
+            "shapely not installed - geometry filter check skipped. "
+            "Install shapely for full geometry filtering support."
+        )
+        return True  # Allow access if shapely not available
+
+    try:
+        item_shape = shape(item_geometry)
+        filter_shape = shape(filter_geometry)
+        return item_shape.intersects(filter_shape)
+    except Exception as e:
+        logger.warning(f"Geometry intersection check failed: {e}")
+        # On error, allow access (fail open)
+        return True