fix picture SPI Quarkus Arc crash + reorganise plugins + sops-nix docs

.env.example

@@ -0,0 +1,40 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Example environment for id.helpwave.de
+# Copy this file to `.env` and fill in the placeholder values.
+#
+# For local development:    docker compose --env-file .env up
+# For NixOS deployment:     see docs/deployment-nixos.md — values map 1:1.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Theme env vars (Keycloakify exposes these as kcContext.properties.<NAME>) ──
+# Public Turnstile site key — rendered into the registration page HTML.
+KC_TURNSTILE_SITE_KEY=0x4AAAAAAAxxxxxxxxxxxxxxxx
+
+# Full URL of the profile-picture SPI for the customer realm. The account
+# console fetches/posts to this from the browser.
+KC_PROFILE_PICTURE_API_URL=https://id.helpwave.de/realms/customer/helpwave-picture
+
+# ── Profile-picture SPI: storage backend ──────────────────────────────────────
+# Keys are read as kc.conf settings; in containerized Keycloak they map to the
+# KC_<KEY_WITH_UNDERSCORES> env var format below.
+
+# Cloudflare R2 example. For AWS S3, leave _ENDPOINT empty and set _REGION to
+# your bucket's actual region.
+KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_REGION=auto
+KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_BUCKET=helpwave-id-avatars
+KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_PUBLIC_BASE_URL=https://cdn.helpwave.de/avatars
+
+# *** Secret — never commit ***
+KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_ACCESS_KEY=changeme
+KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_SECRET_KEY=changeme
+
+# Optional: override the 5 MiB upload limit (value in bytes).
+# KC_SPI_REALM_RESTAPI_EXTENSION_HELPWAVE_PICTURE_MAX_BYTES=5242880
+
+# ── Cloudflare Turnstile secret ───────────────────────────────────────────────
+# Consumed by the realm JSON via the `$${env.TURNSTILE_SECRET}` placeholder, or
+# entered through the admin console per registration flow.
+#
+# *** Secret — never commit ***
+TURNSTILE_SECRET=0x4AAAAAAAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

.github/workflows/ci.yaml

@@ -65,9 +65,9 @@ jobs:
               run: |
                   mkdir -p release-artifacts
                   cp dist_keycloak/keycloak-theme-*.jar release-artifacts/
-                  cp keycloak-extensions/turnstile-authenticator/target/helpwave-turnstile-authenticator-*.jar release-artifacts/
-                  cp keycloak-extensions/privacy-acceptance/target/helpwave-privacy-acceptance-*.jar release-artifacts/
-                  cp keycloak-extensions/profile-picture/target/helpwave-profile-picture-*.jar release-artifacts/
+                  cp keycloak-extensions/captcha/target/helpwave-captcha-*.jar release-artifacts/
+                  cp keycloak-extensions/privacy/target/helpwave-privacy-*.jar release-artifacts/
+                  cp keycloak-extensions/picture/target/helpwave-picture-*.jar release-artifacts/
                   rm -f release-artifacts/original-*.jar
             - uses: softprops/action-gh-release@v2
               with:

README.md

@@ -42,11 +42,12 @@ cd keycloak-extensions
 mvn -DskipTests package
 ```
 
-This produces three jars:
+This produces three jars (each plugin lives in its own folder so it can be built / shipped
+independently):
 
-- `turnstile-authenticator/target/helpwave-turnstile-authenticator-<v>.jar`
-- `privacy-acceptance/target/helpwave-privacy-acceptance-<v>.jar`
-- `profile-picture/target/helpwave-profile-picture-<v>.jar` (shaded with AWS SDK + Thumbnailator)
+- `captcha/target/helpwave-captcha-<v>.jar`
+- `privacy/target/helpwave-privacy-<v>.jar`
+- `picture/target/helpwave-picture-<v>.jar` (shaded with AWS SDK + Thumbnailator)
 
 Drop all three (alongside the theme jar) into Keycloak's `providers/` directory and run
 `kc.sh build`.
@@ -91,7 +92,7 @@ For nixos users, see [docs/nixos.md](docs/nixos.md) for nix-shell setup instruct
 - Field-level validation matching hightide patterns
 - **Cloudflare Turnstile** CAPTCHA on signup (`helpwave-turnstile` FormAction SPI)
 - **Privacy policy** checkbox on signup with acceptance metadata stored on the user
-  (`helpwave-privacy-acceptance` FormAction SPI)
+  (`helpwave-privacy` FormAction SPI)
 - **Profile picture upload** with server-side scaling to multiple sizes and storage in any
   S3-compatible bucket (`helpwave-picture` Realm Resource SPI)
 
@@ -104,9 +105,9 @@ The release workflow publishes the following jars on every version bump in `pack
 | Jar                                              | Purpose                                          |
 |--------------------------------------------------|--------------------------------------------------|
 | `keycloak-theme-for-kc-26.2-and-above.jar`       | The login/account theme                          |
-| `helpwave-turnstile-authenticator-<v>.jar`       | Cloudflare Turnstile registration form action    |
-| `helpwave-privacy-acceptance-<v>.jar`            | Privacy acceptance form action + attribute store |
-| `helpwave-profile-picture-<v>.jar`               | Profile picture REST endpoint + R2/S3 upload     |
+| `helpwave-captcha-<v>.jar`                       | Cloudflare Turnstile registration form action    |
+| `helpwave-privacy-<v>.jar`                       | Privacy acceptance form action + attribute store |
+| `helpwave-picture-<v>.jar`                       | Profile picture REST endpoint + R2/S3 upload     |
 
 Copy all jars into Keycloak's `providers/` directory (or mount them into the container)
 and run `kc.sh build` to rebuild the runtime, then start Keycloak normally.
@@ -196,8 +197,12 @@ KC_PROFILE_PICTURE_API_URL=https://id.helpwave.de/realms/customer/helpwave-pictu
 
 ### 4. NixOS deployment
 
-A complete `services.keycloak` example with `_secret` file handling and the matching
-admin-console steps lives in [docs/deployment-nixos.md](docs/deployment-nixos.md).
+A complete `services.keycloak` example with [sops-nix] secret handling and the matching
+admin-console steps lives in [docs/deployment-nixos.md](docs/deployment-nixos.md). For
+local development with `docker compose`, copy [`.env.example`](.env.example) to `.env`
+and fill in the values.
+
+[sops-nix]: https://github.com/Mic92/sops-nix
 
 ### 5. Releases