chore: add coverage reporting and improve documentation

- Added `pytest-cov` as a development dependency for coverage reporting.
- Configured pytest to include coverage options, ensuring code coverage is reported and enforced.
- Updated the README to include contributing guidelines and logging policies, enhancing clarity for developers.
- Added a new section in the configuration documentation emphasizing the necessity of serving the application over HTTPS in production for security purposes.
- Introduced a new `.coverage` file to track test coverage metrics.

duty_teller/api/app.py

@@ -1,6 +1,7 @@
 """FastAPI app: /api/duties, /api/calendar-events, personal ICS, and static webapp at /app."""
 
 import logging
+import re
 from datetime import date, timedelta
 
 import duty_teller.config as config
@@ -23,6 +24,15 @@ from duty_teller.db.schemas import CalendarEvent, DutyWithUser
 
 log = logging.getLogger(__name__)
 
+# Calendar tokens are secrets.token_urlsafe(32) → base64url, length 43
+_CALENDAR_TOKEN_RE = re.compile(r"^[A-Za-z0-9_-]{40,50}$")
+
+
+def _is_valid_calendar_token(token: str) -> bool:
+    """Return True if token matches expected format (length and alphabet). Rejects invalid before DB."""
+    return bool(token and _CALENDAR_TOKEN_RE.match(token))
+
+
 app = FastAPI(title="Duty Teller API")
 app.add_middleware(
     CORSMiddleware,
@@ -37,7 +47,10 @@ app.add_middleware(
     "/api/duties",
     response_model=list[DutyWithUser],
     summary="List duties",
-    description="Returns duties for the given date range. Requires Telegram Mini App initData (or MINI_APP_SKIP_AUTH / private IP in dev).",
+    description=(
+        "Returns duties for the given date range. Requires Telegram Mini App initData "
+        "(or MINI_APP_SKIP_AUTH / private IP in dev)."
+    ),
 )
 def list_duties(
     request: Request,
@@ -57,7 +70,10 @@ def list_duties(
     "/api/calendar-events",
     response_model=list[CalendarEvent],
     summary="List calendar events",
-    description="Returns calendar events for the date range, including external ICS when EXTERNAL_CALENDAR_ICS_URL is set. Auth same as /api/duties.",
+    description=(
+        "Returns calendar events for the date range, including external ICS when "
+        "EXTERNAL_CALENDAR_ICS_URL is set. Auth same as /api/duties."
+    ),
 )
 def list_calendar_events(
     dates: tuple[str, str] = Depends(get_validated_dates),
@@ -74,7 +90,10 @@ def list_calendar_events(
 @app.get(
     "/api/calendar/ical/{token}.ics",
     summary="Personal calendar ICS",
-    description="Returns an ICS calendar with only the subscribing user's duties. No Telegram auth; access is by secret token in the URL.",
+    description=(
+        "Returns an ICS calendar with only the subscribing user's duties. "
+        "No Telegram auth; access is by secret token in the URL."
+    ),
 )
 def get_personal_calendar_ical(
     token: str,
@@ -84,6 +103,8 @@ def get_personal_calendar_ical(
     Return ICS calendar with only the subscribing user's duties.
     No Telegram auth; access is by secret token in the URL.
     """
+    if not _is_valid_calendar_token(token):
+        return Response(status_code=404, content="Not found")
     user = get_user_by_calendar_token(session, token)
     if user is None:
         return Response(status_code=404, content="Not found")

duty_teller/api/dependencies.py

@@ -105,10 +105,22 @@ def require_miniapp_username(
 
 
 def _is_private_client(client_host: str | None) -> bool:
+    """Return True if client_host is localhost or RFC 1918 private IPv4.
+
+    Used to allow /api/duties without initData when opened from local/private
+    network (e.g. dev). IPv4 only; IPv6 only 127/::1 checked.
+
+    Args:
+        client_host: Client IP or hostname from request.
+
+    Returns:
+        True if loopback or 10.x, 172.16–31.x, 192.168.x.x.
+    """
     if not client_host:
         return False
     if client_host in ("127.0.0.1", "::1"):
         return True
+    # RFC 1918 private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
     parts = client_host.split(".")
     if len(parts) == 4:
         try:

duty_teller/i18n/messages.py

@@ -16,29 +16,48 @@ MESSAGES: dict[str, dict[str, str]] = {
         "calendar_link.private_only": "The /calendar_link command is only available in private chat.",
         "calendar_link.access_denied": "Access denied.",
         "calendar_link.success": "Your personal calendar URL:\n{url}",
-        "calendar_link.help_hint": "Subscribe to this URL in Google Calendar, Apple Calendar, or Outlook to see only your duties.",
+        "calendar_link.help_hint": (
+            "Subscribe to this URL in Google Calendar, Apple Calendar, or Outlook to "
+            "see only your duties."
+        ),
         "calendar_link.error": "Could not generate link. Please try again later.",
         "help.import_schedule": "/import_duty_schedule — Import duty schedule (JSON)",
         "errors.generic": "An error occurred. Please try again later.",
         "pin_duty.group_only": "The /pin_duty command works only in groups.",
         "pin_duty.no_message": "There is no duty message in this chat yet. Add the bot to the group — it will create one automatically.",
         "pin_duty.pinned": "Duty message pinned.",
-        "pin_duty.failed": "Could not pin. Make sure the bot is an administrator with «Pin messages» permission.",
-        "pin_duty.could_not_pin_make_admin": "Duty message was sent but could not be pinned. Make the bot an administrator with «Pin messages» permission, then send /pin_duty in the chat — the current message will be pinned.",
+        "pin_duty.failed": (
+            "Could not pin. Make sure the bot is an administrator with "
+            "«Pin messages» permission."
+        ),
+        "pin_duty.could_not_pin_make_admin": (
+            "Duty message was sent but could not be pinned. Make the bot an "
+            "administrator with «Pin messages» permission, then send /pin_duty in the "
+            "chat — the current message will be pinned."
+        ),
         "duty.no_duty": "No duty at the moment.",
         "duty.label": "Duty:",
         "import.admin_only": "Access for administrators only.",
-        "import.handover_format": "Enter handover time as HH:MM and timezone, e.g. 09:00 Europe/Moscow or 06:00 UTC.",
+        "import.handover_format": (
+            "Enter handover time as HH:MM and timezone, e.g. 09:00 Europe/Moscow or "
+            "06:00 UTC."
+        ),
         "import.parse_time_error": "Could not parse time. Enter e.g.: 09:00 Europe/Moscow",
         "import.send_json": "Send the duty-schedule file (JSON).",
         "import.need_json": "File must have .json extension.",
         "import.parse_error": "File parse error: {error}",
         "import.import_error": "Import error: {error}",
-        "import.done": "Import done: {users} users, {duties} duties{unavailable}{vacation} ({total} events total).",
+        "import.done": (
+            "Import done: {users} users, {duties} duties{unavailable}{vacation} "
+            "({total} events total)."
+        ),
         "import.done_unavailable": ", {count} unavailable",
         "import.done_vacation": ", {count} vacation",
         "api.open_from_telegram": "Open the calendar from Telegram",
-        "api.auth_bad_signature": "Invalid signature. Ensure BOT_TOKEN on the server matches the bot from which the calendar was opened (same bot as in the menu).",
+        "api.auth_bad_signature": (
+            "Invalid signature. Ensure BOT_TOKEN on the server matches the bot from "
+            "which the calendar was opened (same bot as in the menu)."
+        ),
         "api.auth_invalid": "Invalid auth data",
         "api.access_denied": "Access denied",
         "dates.bad_format": "Parameters from and to must be in YYYY-MM-DD format",

duty_teller/services/import_service.py

@@ -21,6 +21,7 @@ def _consecutive_date_ranges(dates: list[date]) -> list[tuple[date, date]]:
     ranges: list[tuple[date, date]] = []
     start_d = end_d = sorted_dates[0]
     for d in sorted_dates[1:]:
+        # Merge consecutive days into one range; gap starts a new range
         if (d - end_d).days == 1:
             end_d = d
         else: