feat(auth): Rexel authentication (OAuth2 PKCE + externally-managed tokens) (#2090)

## Summary

Adds support for Rexel authentication in two modes, plus the gateway
discovery/selection plumbing Rexel requires:

- **OAuth2 PKCE flow** — full interactive login for Rexel accounts
(`pyoverkiz/pkce.py`, `RexelAuthStrategy`).
- **Externally-managed tokens** — `RexelTokenCredentials` +
`RexelTokenAuthStrategy` let a host (e.g. Home Assistant) supply and
refresh tokens it manages itself.
- **Gateway discovery & selection** — Rexel exposes multiple gateways
via the enduser directory; the client now discovers candidates
(`GatewayCandidate`, `SupportsGatewaySelection`), auto-selects a sole
gateway at login, and injects the `gatewayId` header per request,
guarding requests made before selection (`NoGatewaySelectedError`).

### Breaking change
- `auth_headers` is now **async** across all auth strategies. See
`docs/migration-v2.md`.

### Docs
- Getting-started tab for the externally-managed token mode.
- Core-concepts note on the two Rexel auth modes.
- SDK reference renders the auth credentials module.
- Migration guide records the async `auth_headers` change.

## Test Plan
- [x] `pytest` — 488 passed (run in devcontainer)
- [ ] Verify interactive OAuth2 PKCE login against a real Rexel account
- [ ] Verify externally-managed token flow end-to-end from Home
Assistant

Author: iMicknl

docs/core-concepts.md

@@ -79,6 +79,31 @@ States are name/value pairs that represent the current device status, such as cl
 
 The API uses an event listener that you register once per session. Fetching events drains the server-side buffer. Events include execution state changes, device state updates, and other notifications.
 
+## Authentication strategies
+
+The library supports multiple authentication methods depending on the server:
+
+- **Username/Password**: Most cloud servers (Somfy, Cozytouch, Hitachi, Nexity)
+- **Bearer Token**: Cloud servers with pre-issued tokens
+- **Local Token**: Somfy Developer Mode (local gateways)
+- **OAuth2 with PKCE**: Rexel (Azure AD B2C)
+
+Each server automatically selects the appropriate authentication strategy based on the credentials provided.
+
+Rexel supports two authentication modes:
+
+- **Library-driven code exchange** (`RexelOAuthCodeCredentials`): pyoverkiz
+  performs the PKCE code exchange and refreshes its own tokens. Best for
+  standalone use.
+- **Externally-managed token** (`RexelTokenCredentials`): the OAuth2 lifecycle
+  is owned outside the library (e.g. Home Assistant's `application_credentials`
+  platform). Supply an async `access_token_callback` or a static `access_token`.
+  Best when a host application already manages OAuth.
+
+Both Rexel modes support multiple gateways: after `login()`, call
+`discover_gateways()` and `select_gateway()` to scope requests (a sole gateway
+is auto-selected).
+
 ## Relationship diagram
 
 ```

docs/getting-started.md

@@ -150,31 +150,115 @@ Use a cloud server when you want to connect through the vendor’s public API. U
     asyncio.run(main())
     ```
 
-<!-- TODO: Rexel OAuth2 flow not fully working yet
 === "Rexel (cloud)"
 
-    Authentication to the Rexel cloud uses OAuth2 authorization code flow.
-    You need an authorization code and redirect URI obtained from the Rexel OAuth2 consent flow.
+    Authentication to the Rexel cloud uses OAuth2 with PKCE (Proof Key for Code Exchange).
 
-    Use `Server.REXEL` with `RexelOAuthCodeCredentials` to authenticate.
+    **Step 1: Generate PKCE parameters and authorization URL**
 
     ```python
-    import asyncio
+    import secrets
+    from pyoverkiz.pkce import generate_pkce_pair
+    from pyoverkiz.utils import build_rexel_authorization_url
+
+    # Generate PKCE code verifier and challenge
+    code_verifier, code_challenge = generate_pkce_pair()
+
+    # Generate authorization URL (user must visit this in browser)
+    state = secrets.token_urlsafe(16)  # For CSRF protection
+    auth_url = build_rexel_authorization_url(code_challenge, state)
+
+    print(f"Visit this URL to authorize: {auth_url}")
+    ```
+
+    **Step 2: Redirect user to authorization URL**
 
+    Direct the user to the `auth_url`. After successful login, they will be redirected to:
+    ```
+    https://my.home-assistant.io/redirect/oauth?code=AUTHORIZATION_CODE&state=STATE_VALUE
+    ```
+
+    **Step 3: Exchange authorization code for access token**
+
+    ```python
+    import asyncio
     from pyoverkiz.auth.credentials import RexelOAuthCodeCredentials
     from pyoverkiz.client import OverkizClient
     from pyoverkiz.enums import Server
+    from pyoverkiz.const import REXEL_OAUTH_REDIRECT_URI
 
     async def main() -> None:
+        # Use the authorization code from the redirect
         async with OverkizClient(
             server=Server.REXEL,
             credentials=RexelOAuthCodeCredentials(
-                code="your-authorization-code",
-                redirect_uri="https://your-redirect-uri",
+                code="AUTHORIZATION_CODE_FROM_REDIRECT",
+                redirect_uri=REXEL_OAUTH_REDIRECT_URI,
+                code_verifier=code_verifier,  # From step 1
             ),
         ) as client:
             await client.login()
+            # Client is now authenticated and ready to use
 
     asyncio.run(main())
     ```
--->
+
+=== "Rexel (externally-managed token)"
+
+    Use this when an external system already owns the OAuth2 lifecycle — for
+    example the Home Assistant `application_credentials` platform, which
+    authorizes, exchanges, refreshes, and persists tokens for you. pyoverkiz
+    then only needs the *current* access token and the Rexel gateway selection.
+
+    Supply a token in one of two ways:
+
+    **Async callback (recommended for long-running apps).** pyoverkiz calls it
+    before each request, so the owner can refresh and persist transparently.
+
+    ```python
+    import asyncio
+    from pyoverkiz.auth.credentials import RexelTokenCredentials
+    from pyoverkiz.client import OverkizClient
+    from pyoverkiz.enums import Server
+
+
+    async def get_access_token() -> str:
+        # Return a currently-valid access token (refresh upstream as needed).
+        ...
+
+
+    async def main() -> None:
+        async with OverkizClient(
+            server=Server.REXEL,
+            credentials=RexelTokenCredentials(
+                access_token_callback=get_access_token,
+            ),
+        ) as client:
+            await client.login()  # discovers + auto-selects a sole gateway
+
+            gateways = await client.discover_gateways()
+            if len(gateways) > 1:
+                client.select_gateway(gateways[0].gateway_id)
+
+            setup = await client.get_setup()
+            print(f"{len(setup.devices)} device(s)")
+
+    asyncio.run(main())
+    ```
+
+    **Static token (simplest, for quick standalone or test use).** No refresh —
+    when the token expires you construct a new client.
+
+    ```python
+    credentials = RexelTokenCredentials(access_token="YOUR_ACCESS_TOKEN")
+    ```
+
+    **Reload without re-discovering.** Persist the chosen `gateway_id` and pass
+    it back on the next run; `login()` applies it directly and skips discovery:
+
+    ```python
+    credentials = RexelTokenCredentials(
+        access_token_callback=get_access_token,
+        gateway_id="STORED_GATEWAY_ID",
+    )
+    ```

docs/migration-v2.md

@@ -411,3 +411,26 @@ These are not breaking, but worth knowing about when migrating:
 - **Reference endpoints** — query server metadata: `get_reference_ui_classes()`, `get_reference_ui_widgets()`, `get_reference_ui_profile()`, `get_reference_controllable_types()`, etc.
 - **Firmware management** — `get_devices_not_up_to_date()`, `get_device_firmware_status()`, `update_device_firmware()`.
 - **Optional Nexity dependencies** — `boto3` and `warrant-lite` are no longer installed by default. Install them with `pip install "pyoverkiz[nexity]"` if you use the Nexity server. A clear `ImportError` is raised at login time if the extra is missing.
+
+## `auth_headers` is now async
+
+`AuthStrategy.auth_headers()` and every concrete strategy's implementation are
+now coroutines. This only affects code that calls `auth_headers()` directly or
+implements a custom `AuthStrategy` — normal `OverkizClient` use is unaffected.
+
+=== "Before"
+
+    ```python
+    headers = strategy.auth_headers(path)
+    ```
+
+=== "After"
+
+    ```python
+    headers = await strategy.auth_headers(path)
+    ```
+
+Custom strategies must change the method signature to `async def auth_headers`.
+This change lets token-supplied strategies (such as Rexel's
+`RexelTokenAuthStrategy`) await an externally-supplied access-token callback per
+request instead of caching token state.

docs/sdk-reference.md

@@ -11,3 +11,14 @@
 ::: pyoverkiz.exceptions
     options:
       show_source: false
+
+::: pyoverkiz.auth.credentials
+    options:
+      show_source: false
+
+::: pyoverkiz.auth.base
+    options:
+      show_source: false
+      members:
+        - GatewayCandidate
+        - SupportsGatewaySelection

pyoverkiz/auth/__init__.py

@@ -2,11 +2,17 @@
 
 from __future__ import annotations
 
-from pyoverkiz.auth.base import AuthContext, AuthStrategy
+from pyoverkiz.auth.base import (
+    AuthContext,
+    AuthStrategy,
+    GatewayCandidate,
+    SupportsGatewaySelection,
+)
 from pyoverkiz.auth.credentials import (
     Credentials,
     LocalTokenCredentials,
     RexelOAuthCodeCredentials,
+    RexelTokenCredentials,
     TokenCredentials,
     UsernamePasswordCredentials,
 )
@@ -16,8 +22,11 @@
     "AuthContext",
     "AuthStrategy",
     "Credentials",
+    "GatewayCandidate",
     "LocalTokenCredentials",
     "RexelOAuthCodeCredentials",
+    "RexelTokenCredentials",
+    "SupportsGatewaySelection",
     "TokenCredentials",
     "UsernamePasswordCredentials",
     "build_auth_strategy",

pyoverkiz/auth/base.py

@@ -5,7 +5,7 @@
 import datetime
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from typing import Any, Protocol
+from typing import Any, Protocol, runtime_checkable
 
 
 @dataclass(slots=True)
@@ -47,8 +47,37 @@ async def login(self) -> None:
     async def refresh_if_needed(self) -> bool:
         """Refresh tokens if they are expired. Return True if refreshed."""
 
-    def auth_headers(self, path: str | None = None) -> Mapping[str, str]:
+    async def auth_headers(self, path: str | None = None) -> Mapping[str, str]:
         """Generate authentication headers for requests."""
 
+    @property
+    def endpoint(self) -> str:
+        """Return the base API endpoint for requests."""
+
     async def close(self) -> None:
         """Clean up any resources held by the strategy."""
+
+
+@dataclass(slots=True)
+class GatewayCandidate:
+    """A selectable Overkiz gateway behind a multi-account directory."""
+
+    gateway_id: str
+    home_id: str | None = None
+    label: str | None = None
+    external_id: str | None = None
+
+
+@runtime_checkable
+class SupportsGatewaySelection(Protocol):
+    """Optional capability: discover and select among multiple gateways."""
+
+    async def discover_gateways(self) -> list[GatewayCandidate]:
+        """Return all selectable gateways for the authenticated account."""
+
+    def select_gateway(self, gateway_id: str) -> None:
+        """Select the gateway to scope subsequent requests to."""
+
+    @property
+    def selected_gateway(self) -> str | None:
+        """Return the currently selected gateway id, or None."""

pyoverkiz/auth/credentials.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 
 
@@ -32,7 +33,30 @@ class LocalTokenCredentials(TokenCredentials):
 
 @dataclass(slots=True)
 class RexelOAuthCodeCredentials(Credentials):
-    """Credentials using Rexel OAuth2 authorization code."""
+    """Credentials using Rexel OAuth2 authorization code with PKCE."""
 
     code: str = field(repr=False)
     redirect_uri: str
+    code_verifier: str
+
+
+@dataclass(slots=True)
+class RexelTokenCredentials(Credentials):
+    """Rexel credentials backed by an externally-managed access token.
+
+    Use this when the OAuth2 lifecycle is owned outside pyoverkiz (for example
+    Home Assistant's ``application_credentials`` platform). Supply either an
+    async ``access_token_callback`` (called before each request, so the owner
+    can refresh and persist tokens) or a static ``access_token`` for simple
+    standalone or test use. ``gateway_id`` pre-selects a gateway on reload,
+    skipping discovery.
+    """
+
+    access_token_callback: Callable[[], Awaitable[str]] | None = None
+    access_token: str | None = field(default=None, repr=False)
+    gateway_id: str | None = None
+
+    def __post_init__(self) -> None:
+        """Require at least one access-token source."""
+        if not self.access_token_callback and not self.access_token:
+            raise ValueError("Provide either access_token_callback or access_token.")

pyoverkiz/auth/factory.py

@@ -10,6 +10,7 @@
     Credentials,
     LocalTokenCredentials,
     RexelOAuthCodeCredentials,
+    RexelTokenCredentials,
     TokenCredentials,
     UsernamePasswordCredentials,
 )
@@ -20,6 +21,7 @@
     LocalTokenAuthStrategy,
     NexityAuthStrategy,
     RexelAuthStrategy,
+    RexelTokenAuthStrategy,
     SessionLoginStrategy,
     SomfyAuthStrategy,
 )
@@ -66,6 +68,10 @@ def build_auth_strategy(
         )
 
     if server == Server.REXEL:
+        if isinstance(credentials, RexelTokenCredentials):
+            return RexelTokenAuthStrategy(
+                credentials, session, server_config, ssl_context
+            )
         return RexelAuthStrategy(
             _ensure_credentials(credentials, RexelOAuthCodeCredentials),
             session,