Merge remote-tracking branch 'origin/main' into feat/update-default-endpoints

Author: alukach

.github/workflows/deploy-mkdocs.yaml

@@ -0,0 +1,46 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Test docs
+        run: uv run --extra docs mkdocs build --strict
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    if: github.ref_name == 'main'
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Deploy docs
+        run: uv run --extra docs mkdocs gh-deploy --force

.github/workflows/docs.yaml

@@ -5,6 +5,10 @@
 
 ---
 
+[![PyPI - Version][pypi-version-badge]][pypi-link]
+[![GHCR - Version][ghcr-version-badge]][ghcr-link]
+[![GHCR - Size][ghcr-size-badge]][ghcr-link]
+
 STAC Auth Proxy is a proxy API that mediates between the client and your internally accessible STAC API to provide flexible authentication, authorization, and content-filtering mechanisms.
 
 > [!IMPORTANT]
@@ -21,3 +25,15 @@ STAC Auth Proxy is a proxy API that mediates between the client and your interna
 - **🧩 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
 - **🗜️ Response Compression:** Optimize response sizes using [`starlette-cramjam`](https://github.com/developmentseed/starlette-cramjam/)
+
+## Documentation
+
+[Full documentation is available on the website](https://developmentseed.org/stac-auth-proxy).
+
+Head to [Getting Started](https://developmentseed.org/stac-auth-proxy/user-guide/getting-started/) to dig in.
+
+[pypi-version-badge]: https://badge.fury.io/py/stac-auth-proxy.svg
+[pypi-link]: https://pypi.org/project/stac-auth-proxy/
+[ghcr-version-badge]: https://ghcr-badge.egpl.dev/developmentseed/stac-auth-proxy/latest_tag?color=%2344cc11&ignore=latest&label=image+version&trim=
+[ghcr-size-badge]: https://ghcr-badge.egpl.dev/developmentseed/stac-auth-proxy/size?color=%2344cc11&tag=latest&label=image+size&trim=
+[ghcr-link]: https://github.com/developmentseed/stac-auth-proxy/pkgs/container/stac-auth-proxy

README.md

@@ -0,0 +1,31 @@
+# Filtering Data
+
+> [!NOTE]
+>
+> For more information on using filters to solve authorization needs, more information can be found in the [user guide](../user-guide/record-level-auth.md).
+
+## Example Request Flow for multi-record endpoints
+
+```mermaid
+sequenceDiagram
+    Client->>Proxy: GET /collections
+    Note over Proxy: EnforceAuth checks credentials
+    Note over Proxy: BuildCql2Filter creates filter
+    Note over Proxy: ApplyCql2Filter applies filter to request
+    Proxy->>STAC API: GET /collection?filter=(collection=landsat)
+    STAC API->>Client: Response
+```
+
+## Example Request Flow for single-record endpoints
+
+The Filter Extension does not apply to fetching individual records. As such, we must validate the record _after_ it is returned from the upstream API but _before_ it is returned to the user:
+
+```mermaid
+sequenceDiagram
+    Client->>Proxy: GET /collections/abc123
+    Note over Proxy: EnforceAuth checks credentials
+    Note over Proxy: BuildCql2Filter creates filter
+    Proxy->>STAC API: GET /collection/abc123
+    Note over Proxy: ApplyCql2Filter validates the response
+    STAC API->>Client: Response
+```

docs/architecture/data-filtering.md

@@ -0,0 +1 @@
+../CHANGELOG.md