Add CQL2 filter parameter for Authorization (#972)

* upgrade dependencies

* Add 'hidden' filter parameter/header for arbitrary authx to items

Author: philvarner

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## Unreleased - TBD
+
+## Changed
+
+- If a request includes the `STAC-Endpoint` header, that endpoint will be used when generating link hrefs.
+  This deprecates (but still supports) the `X-STAC-Endpoint` header. This change is in order to comply
+  with the proprietary header name recommendations in RFC 6648.
+
+## Added
+
+- To all endpoints that accept a `filter` parameter, add support for a query parameter (GET)
+  or body field (POST) `_filter` or a header `STAC-Filter-Authx` that will "and" a CQL2
+  filter expression to the user's
+  request, such that the extra expression will not be
+  will not be revealed in link contents. This is controlled by the `ENABLE_FILTER_AUTHX`
+  environment variable.
+- To all endpoints that already support the `_collections` parameter, also support a
+  header `STAC-Collections-Authx` to pass the value.
+
 ## [4.3.0] - 2025-07-16
 
 ### Changed

README.md

@@ -53,7 +53,9 @@
     - [Filter Extension](#filter-extension)
     - [Query Extension](#query-extension)
   - [Aggregation](#aggregation)
-  - [Hidden collections filter for authorization](#hidden-collections-filter-for-authorization)
+  - [Collections and filter parameters for authorization](#collections-and-filter-parameters-for-authorization)
+    - [Collections](#collections)
+    - [CQL2 Filter](#cql2-filter)
   - [Ingesting Data](#ingesting-data)
     - [Ingest actions](#ingest-actions)
     - [Ingesting large items](#ingesting-large-items)
@@ -609,7 +611,8 @@ There are some settings that should be reviewed and updated as needeed in the se
 | CORS_CREDENTIALS                 | Configure whether or not to send the `Access-Control-Allow-Credentials` CORS header. Header will be sent if set to `true`.                                                                                                                                                      | none                                                                                 |
 | CORS_METHODS                     | Configure whether or not to send the `Access-Control-Allow-Methods` CORS header. Expects a comma-delimited string, e.g., `GET,PUT,POST`.                                                                                                                                        | `GET,HEAD,PUT,PATCH,POST,DELETE`                                                     |
 | CORS_HEADERS                     | Configure whether or not to send the `Access-Control-Allow-Headers` CORS header. Expects a comma-delimited string, e.g., `Content-Type,Authorization`. If not specified, defaults to reflecting the headers specified in the request’s `Access-Control-Request-Headers` header. | none                                                                                 |
-| ENABLE_COLLECTIONS_AUTHX         | Enables support for hidden `_collections` query parameter / field when set to `true`.                                                                                                                                                                                           | none (not enabled)                                                                   |
+| ENABLE_COLLECTIONS_AUTHX         | Enables support for parameter to restrict collections when set to `true`.                                                                                                                                                                                           | none (not enabled)                                                                   |
+| ENABLE_FILTER_AUTHX         | Enables support for parameter to restrict items when set to `true`.                                                                                                                                                                                           | none (not enabled)                                                                   |
 | ENABLE_THUMBNAILS                | Enables support for presigned thumbnails.                                                                                                                                                                                                                                       | none (not enabled)                                                                   |
 | ENABLE_INGEST_ACTION_TRUNCATE    | Enables support for ingest action "truncate".                                                                                                                                                                                                                                   | none (not enabled)                                                                   |
 | ENABLE_RESPONSE_COMPRESSION      | Enables response compression. Set to 'false' to disable.                                                                                                                                                                                                                        | enabled                                                                              |
@@ -618,6 +621,9 @@ There are some settings that should be reviewed and updated as needeed in the se
 Additionally, the credential for OpenSearch must be configured, as decribed in the
 section [Populating and accessing credentials](#populating-and-accessing-credentials).
 
+If using STAC Server with a proxy in front of it, the base URL for the server, which
+will be used in all link URLs in response bodies, can be set with the `STAC-Endpoint` header.
+
 After reviewing the settings, build and deploy:
 
 ```shell
@@ -1118,16 +1124,32 @@ Available aggregations are:
 - geometry_geohash_grid_frequency ([geohash grid](https://opensearch.org/docs/latest/aggregations/bucket/geohash-grid/) on Item.geometry)
 - geometry_geotile_grid_frequency ([geotile grid](https://opensearch.org/docs/latest/aggregations/bucket/geotile-grid/) on Item.geometry)
 
-## Hidden collections filter for authorization
+## Collections and filter parameters for authorization
 
-All endpoints that involve the use of Collections support the use of a "hidden" query
-parameter named  (for GET requests) or body JSON field (for POST requests) named
-`_collections` that can be used by an authorization proxy (e.g., a pre-hook Lambda)
-to filter the collections a user has access to. This parameter/field will be excluded
-from pagination links, so it does not need to be removed on egress.
+One key concern in stac-server is how to restrict user's access to items.  These
+features allow this introducing support for injecting values at runtime (e.g., in a
+proxy or pre-hook Lambda) to restrict items by collection or by CQL2 filter.
+
+### Collections
 
 This feature must be enabled with the `ENABLE_COLLECTIONS_AUTHX` configuration.
 
+All endpoints that involve the use of Collections support the use of a additional
+parameter that indicates which collections a user should have access to. This parameter
+can be injected as:
+
+1. GET request - a query parameter `_collections`
+2. POST request - a body field `_collections`
+3. All requests - an HTTP header `stac-collections-authx`
+
+This parameter/field will be excluded
+from pagination links, so it does not need to be removed on egress.
+
+If this behavior is enabled and a parameter is not passed or is passed
+with an empty string or empty list, the caller will not have access to any collections.
+When `*` is included in the list of collections (presumably as the only value), the caller
+will have access to all collections.
+
 The endpoints this applies to are:
 
 - /collections
@@ -1141,13 +1163,35 @@ The endpoints this applies to are:
 - /search
 - /aggregate
 
-The five endpoints of the Transaction Extension do not use this parameter, as there are
+The five endpoints of the Transaction Extension do not use these parameters, as there are
 other authorization considerations for these, that are left as future work.
 
-If this behavior is enabled and a `_collections` parameter is not passed or is passed
-with an empty string or empty list, the caller will not have access to any collections.
-When `*` is included in the list of collections (ideally as the only value), the caller
-will have access to all collections.
+### CQL2 Filter
+
+This feature must be enabled with the `ENABLE_FILTER_AUTHX` configuration.
+
+All endpoints that involve items support the use of a additional
+parameter that indicates which items a user should have access to. This parameter
+can be injected as:
+
+1. GET request - a query parameter `_filter`
+2. POST request - a body field `_filter`
+3. All requests - an HTTP header `stac-filter-authx`
+
+This parameter/field will be excluded
+from pagination links, so it does not need to be removed on egress.
+
+The endpoints this applies to are:
+
+- /collections/:collectionId/aggregate
+- /collections/:collectionId/items
+- /collections/:collectionId/items/:itemId
+- /collections/:collectionId/items/:itemId/thumbnail
+- /search
+- /aggregate
+
+One limitation of the header approach is that API Gateway has a hard limit of 10240 or
+8000 bytes (depending on the type), so a large filter could exceed this.
 
 ## Ingesting Data
 

bin/system-tests.sh

@@ -12,6 +12,8 @@ export REQUEST_LOGGING_ENABLED=false
 
 echo "Running tests"
 set +e
+
+# add --match to restrict by test name
 npx ava "./tests/system/${TEST_PATTERN}" --serial --verbose
 TEST_RESULT="$?"
 set -e