Merge branch 'envoy-start' into 'main'

Enable Envoy to run consistently locally and in Docker

See merge request gitlab-org/software-supply-chain-security/authorization/sparkled!6

2 files changed, 88 insertions, 0 deletions

diff --git a/share/man/.keep b/share/man/.keep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/share/man/.keep
diff --git a/share/man/DEVELOPMENT.md b/share/man/DEVELOPMENT.md
new file mode 100644
index 0000000..9d4eaf6
--- /dev/null
+++ b/share/man/DEVELOPMENT.md
@@ -0,0 +1,88 @@
+# Development
+
+Sparkle uses [Envoy Proxy](https://www.envoyproxy.io/) to manage authentication
+via GitLab's Identity Provider (IdP). When a user makes a request without valid
+authentication cookies, Envoy redirects the request to the IdP. It then completes
+an OpenID Connect (OIDC) flow to obtain an `id_token`, `access_token`, and
+`refresh_token`, sets them as cookies, and forwards the request to Sparkle.
+
+This architecture enables Sparkle to focus solely on application logic, without needing to:
+
+* Handle session cookies manually,
+* Exchange refresh tokens for new access tokens, or
+* Access client credentials like `client_id` or `client_secret` directly.
+
+## Request Flow Overview
+
+```plaintext
++-------------+           +---------------+                  +-----------------+                +-------+
+| User-Agent  |           | Proxy (:1000) |                  | Sparkle (:8080) |                | (IdP) |
++-------------+           +---------------+                  +-----------------+                +-------+
+    |                            |                                    |                             |
+    |---> HTTP Request ---------->                                    |                             |
+    |     (no or invalid cookie) |                                    |                             |
+    |                            |                                    |                             |
+    |<--- 302 Redirect to IdP ---|                                    |                             |
+    |                            |                                    |                             |
+    |---------------------------->----------------------------------------------------------------->|
+    |     Auth Request (Login)   |                                    |                             |
+    |                            |                                    |                             |
+    |<------------------------------------------------------------------ Auth Response (Grant) -----|
+    |                            |                                    |                             |
+    |---> Callback to Proxy ---->|                                    |                             |
+    |     (code or token)        |                                    |                             |
+    |                            |---> Exchange Grant for Token ----------------------------------->|
+    |                            |                                    |                             |
+    |                            |<--- ID / Access Token -------------------------------------------|
+    |                            |                                    |                             |
+    |                            |---> Forward Request            --->|                             |
+    |                            |     (Set-Cookie headers)           |                             |
+    |                            |                                    |                             |
+    |                            |<--- Response ----------------------|                             |
+    |<--- Final Response --------|                                    |                             |
+```
+
+## Configuration
+
+Both Envoy and Sparkle are configured via environment variables. You can copy the
+`.env` file to `.env.local` and fill in the required values:
+
+```bash
+cp .env .env.local
+```
+
+The following environment variables must be defined:
+
+| Variable Name          | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `APP_ENV`              | Sparkle environment (default: `development`)     |
+| `BIND_ADDR`            | Address Sparkle listens on (default: `:8080`)    |
+| `OAUTH_CLIENT_ID`      | The client ID registered with GitLab IdP         |
+| `OAUTH_CLIENT_SECRET`  | The corresponding client secret                  |
+| `OAUTH_REDIRECT_URL`   | Redirect URI configured in your GitLab OAuth app |
+| `OIDC_ISSUER`          | The issuer URL (e.g., `http://gdk.test:3000`)    |
+
+You can refer to the `Dockerfile` in the root of this repository to determine the
+exact version of Envoy required. To install Envoy locally, follow the [official
+installation guide](https://www.envoyproxy.io/docs/envoy/latest/start/install).
+
+Sparkle uses the following Envoy Filters:
+
+* [envoy.filters.http.oauth2](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/oauth2_filter)
+* [envoy.filters.http.router](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter)
+
+## Usage
+
+You can run Sparkle and Envoy either natively or in Docker:
+
+* **Run Sparkle + Envoy on the host machine:**
+
+  ```bash
+  $ make run
+  ```
+
+* **Run Sparkle + Envoy in Docker:**
+
+  ```bash
+  $ make run-image
+  ```