test: reproduce and block unsafe broker auto-link

docs/first-broker-login-security.md

@@ -0,0 +1,27 @@
+# First Broker Login security
+
+Keycloak 26.7.0's built-in `first broker login` flow does **not** silently
+auto-link by email. It contains:
+
+- `Create User If Unique`
+- `Handle Existing Account`
+- `Confirm link existing account`
+- email verification or re-authentication ownership proof
+
+`Automatically set existing user` is an explicit, dangerous opt-in. The local
+acceptance harness copies the built-in flow, enables AutoLink, disables the
+ownership-proof branch, and signs in through a controllable OIDC account whose
+email collides with `regular-user`. It verifies that the external identity is
+attached without proof. The harness then assigns the original built-in flow,
+repeats the login, observes the existing-account confirmation page, and verifies
+that no federated identity was attached.
+
+Run after the stack is healthy:
+
+```bash
+./scripts/verify-first-broker-login.sh
+```
+
+The vulnerable flow remains only as a disabled learning artifact. The
+`mock-google` provider is always returned to the secure built-in flow at the end
+of the verification.