diff --git a/.env.example b/.env.example index 085f0d8..f3c8488 100644 --- a/.env.example +++ b/.env.example @@ -28,7 +28,9 @@ PRONOTE_AUTH_MODE=password # PRONOTE_ACCOUNT_PIN= # --- CalDAV --- -CALDAV_URL=https://caldav.example.com/calendars/user/pronote/ +# Endpoint commun (URL potentiellement sensible, masquée dans les journaux) +CALDAV_ENDPOINT__URL=https://caldav.example.com/calendars/user/pronote/ +# Ancien nom temporairement supporté avec un avertissement de dépréciation : CALDAV_URL CALDAV_USERNAME=user@example.com CALDAV_PASSWORD=your_caldav_password CALDAV_CALENDAR_PATH=/pronote-sync/ diff --git a/GUIDE_DEV_PYTHON.md b/GUIDE_DEV_PYTHON.md index e5a04c7..c216b09 100644 --- a/GUIDE_DEV_PYTHON.md +++ b/GUIDE_DEV_PYTHON.md @@ -264,7 +264,7 @@ Le projet utilise **`pydantic-settings`** pour valider et charger la configurati | `PRONOTE_USERNAME` | Identifiant Pronote (si `pronotepy` utilisé). | `parent.dupont` | `str` | | `PRONOTE_PASSWORD` | Mot de passe Pronote (si `pronotepy` utilisé). | `SecretStr` (masqué) | `SecretStr` | | `PRONOTE_ENT` | Slug ENT supporté, résolu vers une fonction de `pronotepy.ent`. | `monbureaunumerique` | `str` | -| `CALDAV_URL` | URL du serveur CalDAV (masquée en `SecretStr`). | `https://caldav.example.com/calendars/...` | `SecretStr` | +| `CALDAV_ENDPOINT__URL` | URL du serveur CalDAV, via l'endpoint commun (masquée en `SecretStr`). | `https://caldav.example.com/calendars/...` | `ExternalEndpoint` | | `CALDAV_USERNAME` | Identifiant CalDAV. | `user@example.com` | `str` | | `CALDAV_PASSWORD` | Mot de passe CalDAV. | `SecretStr` (masqué) | `SecretStr` | | `CALDAV_CALENDAR_PATH` | Chemin du calendrier CalDAV de destination. | `/pronote-sync/` | `str` | diff --git a/pronote_sync/config/settings.py b/pronote_sync/config/settings.py index 888af9a..9791542 100644 --- a/pronote_sync/config/settings.py +++ b/pronote_sync/config/settings.py @@ -10,21 +10,76 @@ from __future__ import annotations import warnings from datetime import date -from typing import Literal +from typing import Annotated, Literal from urllib.parse import urlparse from pydantic import ( + AfterValidator, + BaseModel, + ConfigDict, Field, SecretStr, - ValidationInfo, field_serializer, - field_validator, model_validator, ) from pydantic_settings import BaseSettings, SettingsConfigDict from pronote_sync.utils.redaction import redact_url +_EXTERNAL_ENDPOINT_SCHEMES: frozenset[str] = frozenset({"file", "http", "https"}) +_LOOPBACK_HOSTS: frozenset[str] = frozenset({"localhost", "127.0.0.1", "::1"}) + + +def _validate_external_endpoint_url(value: SecretStr) -> SecretStr: + """Valide la structure et le schéma d'une URL d'endpoint externe. + + :param value: URL potentiellement sensible à valider. + :return: URL validée, toujours encapsulée dans ``SecretStr``. + :rtype: SecretStr + :raises ValueError: Si l'URL est malformée ou utilise un schéma inconnu. + """ + is_valid = False + try: + parsed = urlparse(value.get_secret_value()) + _ = parsed.port + is_valid = ( + parsed.scheme in _EXTERNAL_ENDPOINT_SCHEMES + and (parsed.scheme not in {"http", "https"} or parsed.hostname is not None) + and (parsed.scheme != "file" or bool(parsed.path)) + ) + except ValueError: + pass + if not is_valid: + raise ValueError("Endpoint externe invalide : URL ou schéma non supporté") from None + return value + + +EndpointUrl = Annotated[SecretStr, AfterValidator(_validate_external_endpoint_url)] + + +class ExternalEndpoint(BaseModel): + """Représente un endpoint externe potentiellement sensible. + + Le socle accepte les transports ``https``, ``http`` et ``file``. Chaque + connecteur restreint ensuite cette liste selon sa propre politique de + sécurité. L'URL reste encapsulée dans :class:`pydantic.SecretStr` et sa + sérialisation conserve uniquement une représentation expurgée. + """ + + model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True) + + url: EndpointUrl + + @field_serializer("url") + def _serialize_url(self, value: SecretStr) -> str: + """Expurge l'URL lors de la sérialisation. + + :param value: URL encapsulée à sérialiser. + :return: URL expurgée. + :rtype: str + """ + return redact_url(value.get_secret_value()) + class PronoteSettings(BaseSettings): """Paramètres d'accès à Pronote (flux iCal et API ``pronotepy``). @@ -91,73 +146,88 @@ class CalDAVSettings(BaseSettings): Les variables d'environnement correspondantes sont préfixées par ``CALDAV_``. L'URL est traitée comme potentiellement sensible (au même - titre que ``PRONOTE_ICAL_URL``) : elle est de type ``SecretStr`` et + titre que ``PRONOTE_ICAL_ENDPOINT__URL``) : elle est de type ``SecretStr`` et masquée lors de la sérialisation. Par défaut, seul HTTPS est accepté ; HTTP n'est toléré que pour un hôte de boucle locale (``localhost``, ``127.0.0.1``, ``::1``) lorsque ``allow_insecure_http`` vaut ``True``. + Le nouvel endpoint se configure avec ``CALDAV_ENDPOINT__URL`` ; + ``CALDAV_URL`` reste temporairement pris en charge avec un avertissement + de dépréciation. """ - model_config = SettingsConfigDict(env_file=".env", extra="ignore", env_prefix="CALDAV_") + model_config = SettingsConfigDict( + env_file=".env", + env_nested_delimiter="__", + extra="ignore", + env_prefix="CALDAV_", + ) allow_insecure_http: bool = False - url: SecretStr | None = None + endpoint: ExternalEndpoint | None = None + url: SecretStr | None = Field( + default=None, + exclude=True, + deprecated="Utiliser endpoint.url à la place (CALDAV_URL obsolète).", + ) username: str | None = None password: SecretStr | None = None calendar_path: str = "/pronote-sync/" - @field_serializer("url") - def _serialize_url(self, value: SecretStr | None) -> str | None: - """Masque l'URL CalDAV lors de la sérialisation (repr, str, JSON). - - :param value: Valeur du champ ``url`` (secret potentiel). - :return: URL avec les éléments sensibles remplacés par ``REDACTED``, - ou ``None`` si la valeur est absente. - :rtype: str | None - """ - if value is None: - return None - return redact_url(value.get_secret_value()) - - @field_validator("url") + @model_validator(mode="before") @classmethod - def _validate_url_https(cls, v: SecretStr | None, info: ValidationInfo) -> SecretStr | None: - """Valide le schéma de l'URL CalDAV (HTTPS obligatoire par défaut). + def _migrate_legacy_url(cls, data: object) -> object: + """Migre ``url`` vers l'endpoint commun avec un avertissement. + + :param data: Données brutes du modèle. + :return: Données complétées avec ``endpoint`` si nécessaire. + :rtype: object + """ + if not isinstance(data, dict) or data.get("url") is None: + return data + migrated_data = data.copy() + warnings.warn( + "CALDAV_URL est obsolète : utiliser CALDAV_ENDPOINT__URL.", + DeprecationWarning, + stacklevel=2, + ) + if migrated_data.get("endpoint") is None: + migrated_data["endpoint"] = {"url": migrated_data["url"]} + return migrated_data + + @model_validator(mode="after") + def _validate_endpoint_policy(self) -> CalDAVSettings: + """Applique la politique HTTPS/HTTP loopback propre à CalDAV. HTTPS est toujours accepté. HTTP n'est accepté que pour un hôte de boucle locale (``localhost``, ``127.0.0.1``, ``::1``) et uniquement - lorsque ``allow_insecure_http`` vaut ``True``. Les messages d'erreur - ne contiennent jamais l'URL brute (susceptible de contenir des - identifiants). + lorsque ``allow_insecure_http`` vaut ``True``. Les autres schémas du + socle commun sont refusés pour ce connecteur. - :param v: Valeur du champ ``url`` à valider. - :param info: Contexte de validation (accès aux autres champs). - :return: La valeur validée inchangée. - :rtype: SecretStr | None + :return: Instance validée inchangée. + :rtype: CalDAVSettings :raises ValueError: Si le schéma n'est pas supporté ou si l'URL HTTP n'est pas autorisée. """ - if v is None: - return v - raw_url = v.get_secret_value() + if self.endpoint is None: + return self + raw_url = self.endpoint.url.get_secret_value() parsed = urlparse(raw_url) if parsed.scheme not in ("http", "https"): raise ValueError("URL CalDAV invalide : schéma non supporté") from None if parsed.scheme == "https": - return v + return self # HTTP — check allow_insecure_http flag and loopback - allow_insecure = info.data.get("allow_insecure_http", False) - if not allow_insecure: + if not self.allow_insecure_http: raise ValueError( "URL CalDAV non sécurisée : HTTPS requis (ou activer " "CALDAV_ALLOW_INSECURE_HTTP pour localhost)" ) from None hostname = parsed.hostname or "" - loopback_hosts = {"localhost", "127.0.0.1", "::1"} - if hostname not in loopback_hosts: + if hostname not in _LOOPBACK_HOSTS: raise ValueError( "URL CalDAV non sécurisée : HTTP autorisé uniquement pour localhost" ) from None - return v + return self _XMPP_LOOPBACK_HOSTS: frozenset[str] = frozenset({"localhost", "127.0.0.1", "::1"}) @@ -342,7 +412,7 @@ class Settings(BaseSettings): self.pronote.password, self.pronote.qr_pin, self.pronote.account_pin, - self.caldav.url, + self.caldav.endpoint.url if self.caldav.endpoint is not None else None, self.caldav.password, self.xmpp.password, self.ai.api_key, diff --git a/pronote_sync/sync/caldav.py b/pronote_sync/sync/caldav.py index 4839a3d..0cb5ca0 100644 --- a/pronote_sync/sync/caldav.py +++ b/pronote_sync/sync/caldav.py @@ -79,11 +79,12 @@ class CalDAVGateway: else cast(Callable[..., Any], caldav.DAVClient) ) self._calendar_path: str = settings.calendar_path + url_secret = settings.endpoint.url if settings.endpoint is not None else None self._redacted_url: str | None = ( - redact_url(settings.url.get_secret_value()) if settings.url else None + redact_url(url_secret.get_secret_value()) if url_secret else None ) self._username: str | None = settings.username - self._url_secret: SecretStr | None = settings.url + self._url_secret: SecretStr | None = url_secret self._password_secret: SecretStr | None = settings.password self._client: Any = None self._calendar: Any = None diff --git a/pronote_sync/sync/synchronizer.py b/pronote_sync/sync/synchronizer.py index 20d34f5..13f5d97 100644 --- a/pronote_sync/sync/synchronizer.py +++ b/pronote_sync/sync/synchronizer.py @@ -96,7 +96,7 @@ def synchronize( ) if ( - settings.caldav.url is None + settings.caldav.endpoint is None or settings.caldav.username is None or settings.caldav.password is None ):