feat(contract): add opt-in MAX configuration and lifecycle

Refs #81

app/config.py

@@ -1,10 +1,12 @@
 """Typed application settings. The only place that reads environment variables."""
 
+import re
 from functools import lru_cache
 from pathlib import Path
 from typing import Literal
+from urllib.parse import urlsplit
 
-from pydantic import Field
+from pydantic import Field, SecretStr, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 ROOT_DIR = Path(__file__).resolve().parent.parent
@@ -43,6 +45,36 @@ class Settings(BaseSettings):
     tg_bot_token: str = ""
     doctor_notify_chat_id: int | None = None
 
+    # MAX is opt-in. Its adapter is delivered in the related backend/channel changes.
+    max_enabled: bool = False
+    max_bot_token: SecretStr = SecretStr("")
+    max_bot_username: str = ""
+    max_webhook_secret: SecretStr = SecretStr("")
+    max_webhook_url: str = ""
+    max_site_url: str = ""
+    max_ca_bundle: Path | None = None
+    max_link_ttl_seconds: int = Field(default=600, ge=60, le=1800)
+
+    @model_validator(mode="after")
+    def validate_max(self) -> "Settings":
+        if not self.max_enabled:
+            return self
+        if not self.max_bot_token.get_secret_value().strip():
+            raise ValueError("MAX_BOT_TOKEN is required when MAX_ENABLED=true")
+        if not re.fullmatch(r"[A-Za-z0-9_]{1,128}", self.max_bot_username):
+            raise ValueError("MAX_BOT_USERNAME must be the bot nickname without @ or a URL")
+        if not re.fullmatch(r"[A-Za-z0-9_-]{32,256}", self.max_webhook_secret.get_secret_value()):
+            raise ValueError("MAX_WEBHOOK_SECRET must contain 32..256 URL-safe characters")
+        for name, value in (("MAX_SITE_URL", self.max_site_url), ("MAX_WEBHOOK_URL", self.max_webhook_url)):
+            url = urlsplit(value)
+            if url.scheme != "https" or not url.hostname or url.username or url.password or url.port not in (None, 443):
+                raise ValueError(f"{name} must use HTTPS on port 443 without credentials")
+            if url.query or (name == "MAX_WEBHOOK_URL" and url.fragment):
+                raise ValueError(f"{name} must not contain a query string (or a fragment for webhook)")
+        if self.max_ca_bundle is not None and not self.max_ca_bundle.is_file():
+            raise ValueError("MAX_CA_BUNDLE must point to an existing trusted CA bundle")
+        return self
+
     # Virtual clock for the demo (ADR-005).
     demo_clock: bool = True
     tz: str = "Europe/Moscow"