"""OpenID Connect helpers beyond the authentication backend.

Signing out has two halves. Clearing the Django session is not enough: Keycloak
keeps its own session, so the next request to a protected page silently signs the
user back in and the sign-in screen is never shown. ``provider_logout`` is wired
to ``OIDC_OP_LOGOUT_URL_METHOD`` and builds the realm's RP-initiated logout URL,
which ends the Keycloak session too and returns the browser to the platform root.

Endpoints come from settings (django-environ); nothing is hard-coded.
"""
from urllib.parse import urlencode

from django.conf import settings


def provider_logout(request):
    """Return Keycloak's end-session URL for the current session.

    mozilla-django-oidc calls this before flushing the Django session, so the
    stored id token is still available. ``id_token_hint`` tells Keycloak which
    session to end, and ``post_logout_redirect_uri`` is where it sends the
    browser afterwards — that URI must be registered on the client
    (``post.logout.redirect.uris``) or Keycloak refuses to redirect back.
    """
    id_token = request.session.get("oidc_id_token", "")
    params = {"post_logout_redirect_uri": request.build_absolute_uri("/")}
    if id_token:
        params["id_token_hint"] = id_token
    return f"{settings.OIDC_OP_LOGOUT_ENDPOINT}?{urlencode(params)}"