Add OIDC back-channel logout with session indexes

packages/kaya-oidc/README.md

@@ -128,6 +128,50 @@ app = KayaApp(mixins=[session, google, github])
 > default provider is `default`). Existing logged-in users are signed out once
 > and simply re-authenticate.
 
+## Back-channel logout
+
+Set `backchannel_logout_path` to accept OIDC Back-Channel Logout tokens from
+the provider:
+
+```python
+OIDCConfig(
+    issuer=os.environ['OIDC_ISSUER'],
+    client_id=os.environ['OIDC_CLIENT_ID'],
+    client_secret=os.environ['OIDC_CLIENT_SECRET'],
+    redirect_uri='https://example.com/auth/callback',
+    backchannel_logout_path='/auth/backchannel-logout',
+)
+```
+
+Register the corresponding absolute URL (for example
+`https://example.com/auth/backchannel-logout`) as the client's back-channel
+logout URI with the provider. This registration happens at the provider; it is
+not part of OIDC discovery. With `OIDCProviders`, enabling the option derives
+`{base_path}/{provider}/backchannel-logout` for that provider.
+
+The endpoint accepts form-encoded `POST` requests containing `logout_token`.
+It validates the JWT signature against the provider JWKS, the `logout+jwt`
+type, issuer, audience, `iat`, `jti`, and the back-channel logout event, and
+rejects tokens containing `nonce`. A token with `sid` logs out sessions for
+that provider session; without `sid`, `sub` logs out all sessions for that
+subject. Under `multi-identity`, only the named provider's identity is removed
+from a shared session. Valid requests return `200` with
+`Cache-Control: no-store`, including when the session is already gone. Invalid
+requests return `400`.
+
+Back-channel logout requires a session store with index support. All built-in
+stores (`InMemorySessionStore`, `RedisSessionStore`, and
+`MemcacheSessionStore`) support it. `OIDCMixin` raises immediately if the
+configured store does not. Sessions created before upgrading are indexed on
+their next request.
+
+Logout tokens must be asymmetrically signed; unsigned tokens, HMAC signatures,
+and encrypted logout tokens (JWE) are not supported. `jti` is required, but no
+replay cache is maintained: repeating a valid logout request is idempotent.
+`backchannel_logout_leeway` controls the allowed clock skew (60 seconds by
+default). For a templated Microsoft Entra issuer, the logout token must carry
+`tid`, just as for ID token validation.
+
 ## Pushed authorization requests (PAR)
 
 `OIDCConfig.par` controls RFC 9126 Pushed Authorization Requests:
@@ -172,6 +216,7 @@ authentication methods (`private_key_jwt`, mTLS) is not supported.
 - Optional userinfo endpoint fetch
 - Refresh token support
 - RP-initiated logout (when provider advertises `end_session_endpoint`)
+- Back-channel logout (`sid` and `sub` session invalidation)
 - Pushed Authorization Requests (RFC 9126) via `OIDCConfig.par`
 - Multiple providers in one app via `OIDCProviders` (or several `OIDCMixin` instances)
 - `single-identity` (default) or `multi-identity` session strategy