docs(bff): demo note for the BFF front door (S-07) (refs #8)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/demo-script.md

@@ -5,6 +5,43 @@ copy-pasteable walkthrough against a local `make up` stack.
 
 ---
 
+## S-07 — BFF: the portals' single backend
+
+**Outcome:** the BFF validates Keycloak `digid` tokens on the self-service submit (forwarding the
+bsn to the domain) and serves the openbaar register anonymously with only public-safe fields — the
+front door the portals (S-08/S-09) will talk to.
+
+**The path:** portal → BFF `POST /self-service/registrations` (token-gated) → domain; and
+BFF `GET /openbaar/register` (anonymous) → projection-api. See ADR-0010.
+
+```bash
+# 1. Bring the full stack up.
+make up
+
+# 2. Drive the BFF end-to-end (401 without a token, 202 with a real digid token, anonymous openbaar).
+make verify-bff        # → "OK — BFF: 401 without token, 202 with a digid token, anonymous ..."
+
+# 3. Try it by hand (BFF on host port 8080).
+#    a) A digid access token for the mock user jan-burger (bsn 123456782):
+tok=$(curl -s -X POST http://localhost:8180/realms/digid/protocol/openid-connect/token \
+  -d grant_type=password -d client_id=big-portal -d username=jan-burger -d password=test123 \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
+
+#    b) Submit — without the token it is 401; with it, 202:
+curl -s -o /dev/null -w "no token  -> %{http_code}\n" -X POST http://localhost:8080/self-service/registrations
+curl -s -o /dev/null -w "with token-> %{http_code}\n" -X POST http://localhost:8080/self-service/registrations \
+  -H "Authorization: Bearer $tok"
+
+#    c) The openbaar register is anonymous and exposes only id + status (never the bsn):
+curl -fsS http://localhost:8080/openbaar/register | jq
+```
+
+> The self-service token is validated against Keycloak's `digid` realm; the openbaar lookup needs no
+> token (S-09). The generated contract lives at `services/bff/openapi.json` — S-08's client is built
+> from it.
+
+---
+
 ## S-05 — BIG Domain Service: submit a registration
 
 **Outcome:** submitting a registration starts a Flowable process; the external-task worker