Merge remote-tracking branch 'origin/dev' into fix/clinical-review-safety

tests/test_api_max.py

@@ -0,0 +1,103 @@
+"""MAX endpoints authenticate before reading bindings or accepting events."""
+
+import sys
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.exc import OperationalError
+
+from app.config import get_settings
+from app.core import clock
+from app.db import repo, session
+from app.db.bootstrap import init_db
+from app.integrations import max_store
+from app.main import app
+
+BASE = "/api/v1/me/notifications/max"
+HOOK = "/api/v1/webhooks/max"
+TOKEN = "synthetic-patient"
+AUTH = {"Authorization": f"Bearer {TOKEN}"}
+SECRET = "test-secret-" * 4
+
+
+@pytest.fixture
+async def client(monkeypatch):
+    for key, value in {
+        "MAX_ENABLED": "true",
+        "MAX_BOT_TOKEN": "fake-token",
+        "MAX_BOT_USERNAME": "test_bot",
+        "MAX_WEBHOOK_SECRET": SECRET,
+        "MAX_WEBHOOK_URL": "https://api.example.org" + HOOK,
+        "MAX_SITE_URL": "https://example.org",
+    }.items():
+        monkeypatch.setenv(key, value)
+    get_settings.cache_clear()
+    await session.configure(identity_url="sqlite+aiosqlite:///:memory:", clinical_url="sqlite+aiosqlite:///:memory:")
+    await init_db()
+    async with session.get_clinical_session() as s:
+        await repo.upsert_profile(s, token=TOKEN, doctor_id="")
+        await repo.set_dialog_state(
+            s, token=TOKEN, state="idle", data={"consent": True, "adult": True}, now=clock.now()
+        )
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
+        yield c
+    await session.configure()
+    get_settings.cache_clear()
+
+
+@pytest.mark.parametrize("auth", [{}, {"Authorization": "Bearer unknown"}, {"Authorization": "Basic test"}])
+async def test_auth_required(client, auth):
+    assert (await client.get(BASE, headers=auth)).status_code == 401
+    assert (await client.post(BASE + "/link", headers=auth, json={"consent": True})).status_code == 401
+    assert (await client.delete(BASE, headers=auth)).status_code == 401
+
+
+async def test_link_requires_consent_and_hides_patient_credential(client):
+    for body in ({}, {"consent": False}, {"consent": True, "user_id": 100}):
+        assert (await client.post(BASE + "/link", headers=AUTH, json=body)).status_code == 422
+    response = await client.post(BASE + "/link", headers=AUTH, json={"consent": True})
+    assert response.status_code == 200
+    assert TOKEN not in response.text
+    url = urlsplit(response.json()["url"])
+    assert url.netloc == "max.ru" and url.path == "/test_bot"
+    code = parse_qs(url.query)["start"][0]
+    async with session.get_identity_session() as s:
+        assert await max_store.bind(s, code, 100, clock.now()) == TOKEN
+    assert (await client.get(BASE, headers=AUTH)).json()["connected"] is True
+    assert (await client.delete(BASE, headers=AUTH)).json()["connected"] is False
+
+
+async def test_revoke_consent_prevents_linking(client):
+    async with session.get_clinical_session() as s:
+        await repo.set_dialog_state(
+            s, token=TOKEN, state="idle", data={"consent": False, "adult": True}, now=clock.now()
+        )
+    assert (await client.post(BASE + "/link", headers=AUTH, json={"consent": True})).status_code == 403
+
+
+async def test_disabled_service_still_allows_disconnect(client, monkeypatch):
+    monkeypatch.setenv("MAX_ENABLED", "false")
+    get_settings.cache_clear()
+    assert (await client.get(BASE, headers=AUTH)).json()["available"] is False
+    assert (await client.post(BASE + "/link", headers=AUTH, json={"consent": True})).status_code == 503
+    assert (await client.post(HOOK, json={})).status_code == 503
+    assert (await client.delete(BASE, headers=AUTH)).status_code == 200
+
+
+async def test_webhook_secret_checked_before_body_or_adapter(client):
+    assert (await client.post(HOOK, content="not-json")).status_code == 403
+    assert (await client.post(HOOK, headers={"X-Max-Bot-Api-Secret": "wrong"}, json={})).status_code == 403
+    headers = {"X-Max-Bot-Api-Secret": SECRET}
+    assert (await client.post(HOOK, headers=headers, content="not-json")).status_code == 400
+    assert (await client.post(HOOK, headers=headers, json=[])).status_code == 422
+    assert (await client.post(HOOK, headers=headers, content=" " * 65537)).status_code == 413
+
+
+async def test_webhook_storage_failure_is_retryable_without_identity_details(client, monkeypatch):
+    handler = AsyncMock(side_effect=OperationalError("private SQL", {"token": TOKEN}, Exception("private")))
+    monkeypatch.setitem(sys.modules, "app.channels.max_bot", SimpleNamespace(handle_update=handler))
+    response = await client.post(HOOK, headers={"X-Max-Bot-Api-Secret": SECRET}, json={})
+    assert response.status_code == 503 and TOKEN not in response.text and "private" not in response.text

tests/test_contracts_max.py

@@ -0,0 +1,47 @@
+"""MAX stays off without credentials; enabled deployments fail closed on incomplete settings."""
+
+import pytest
+from pydantic import ValidationError
+
+from app.config import Settings
+
+
+def configured(**overrides):
+    fields = {
+        "max_enabled": True,
+        "max_bot_token": "test-only-token",
+        "max_bot_username": "test_bot",
+        "max_webhook_secret": "test-only-secret-" * 3,
+        "max_webhook_url": "https://api.example.org/api/v1/webhooks/max",
+        "max_site_url": "https://patient.example.org/#/today",
+    }
+    return Settings(_env_file=None, **(fields | overrides))
+
+
+def test_max_disabled_by_default():
+    assert not Settings(_env_file=None).max_enabled
+
+
+def test_max_secrets_are_redacted():
+    settings = configured()
+    assert "test-only-token" not in repr(settings)
+    assert "test-only-secret" not in repr(settings)
+
+
+@pytest.mark.parametrize(
+    "overrides",
+    [
+        {"max_bot_token": ""},
+        {"max_bot_username": "@test_bot"},
+        {"max_webhook_secret": "short"},
+        {"max_site_url": "http://patient.example.org"},
+        {"max_webhook_url": "http://api.example.org"},
+        {"max_webhook_url": "https://api.example.org:8443/hook"},
+        {"max_webhook_url": "https://user:password@api.example.org/hook"},
+        {"max_webhook_url": "https://api.example.org/hook#fragment"},
+        {"max_site_url": "https://patient.example.org?token=credential"},
+    ],
+)
+def test_max_rejects_incomplete_or_unsafe_settings(overrides):
+    with pytest.raises(ValidationError):
+        configured(**overrides)

tests/test_contracts_settings_privacy.py

@@ -0,0 +1,21 @@
+"""Startup validation errors must not print configuration credentials."""
+
+import pytest
+from pydantic import ValidationError
+
+from app.config import Settings
+
+
+def test_incomplete_max_configuration_does_not_expose_token():
+    with pytest.raises(ValidationError) as error:
+        Settings(_env_file=None, max_enabled=True, max_bot_token="SYNTHETIC_SECRET")
+    message = str(error.value)
+    assert "MAX_BOT_USERNAME" in message
+    assert "SYNTHETIC_SECRET" not in message and "input_value" not in message
+
+
+def test_invalid_field_does_not_expose_accidentally_pasted_secret():
+    with pytest.raises(ValidationError) as error:
+        Settings(_env_file=None, max_enabled="SYNTHETIC_SECRET")
+    assert "max_enabled" in str(error.value)
+    assert "SYNTHETIC_SECRET" not in str(error.value)

tests/test_db.py

@@ -53,7 +53,15 @@ async def _tables(engine_fn: Callable[[], AsyncEngine]) -> set[str]:
 async def test_create_all_puts_tables_in_the_right_db(dbs: None) -> None:
     identity_tables = await _tables(session.identity_engine)
     clinical_tables = await _tables(session.clinical_engine)
-    assert identity_tables == {"patients", "doctors", "connect_codes"}
+    assert identity_tables == {
+        "patients",
+        "doctors",
+        "connect_codes",
+        "max_bindings",
+        "max_link_codes",
+        "max_webhook_receipts",
+        "max_deliveries",
+    }
     assert {
         "patient_profiles",
         "item_responses",

tests/test_integrations_max.py

@@ -0,0 +1,123 @@
+"""Persistent, one-time linking and queue recovery; synthetic identities only."""
+
+from datetime import timedelta
+
+import pytest
+from sqlalchemy import select
+
+from app.core import clock
+from app.db import repo, session
+from app.db.bootstrap import init_db
+from app.db.clinical import ScaleResult
+from app.db.max_notifications import MaxBinding, MaxDelivery, MaxLinkCode
+from app.integrations import max_store as store
+
+
+@pytest.fixture(autouse=True)
+async def database():
+    await session.configure(identity_url="sqlite+aiosqlite:///:memory:", clinical_url="sqlite+aiosqlite:///:memory:")
+    await init_db()
+    yield
+    await session.configure()
+
+
+async def test_codes_are_hashed_expiring_one_time_and_replaced():
+    now = clock.now()
+    async with session.get_identity_session() as s:
+        old, _ = await store.issue_code(s, "patient", now, 60)
+        code, expires = await store.issue_code(s, "patient", now, 60)
+        assert await store.code_token(s, old, now) is None
+        row = (await s.scalars(select(MaxLinkCode))).one()
+        assert row.digest != code and row.digest == store.digest(code)
+        assert await store.code_token(s, code, expires) is None
+        assert await store.bind(s, code, 100, now) == "patient"
+        assert await store.bind(s, code, 100, now) is None
+    async with session.get_identity_session() as s:
+        assert (await s.get(MaxBinding, "patient")).user_id == 100
+
+
+async def test_active_binding_cannot_be_reassigned_in_either_direction():
+    now = clock.now()
+    async with session.get_identity_session() as s:
+        code, _ = await store.issue_code(s, "one", now, 60)
+        await store.bind(s, code, 100, now)
+        code, _ = await store.issue_code(s, "two", now, 60)
+        assert await store.bind(s, code, 100, now) is None
+        assert await store.code_token(s, code, now) == "two"
+        code, _ = await store.issue_code(s, "one", now, 60)
+        assert await store.bind(s, code, 200, now) is None
+        await store.disconnect(s, "one")
+        assert await store.code_token(s, code, now) is None
+        code, _ = await store.issue_code(s, "two", now, 60)
+        assert await store.bind(s, code, 100, now) == "two"
+
+
+async def test_disconnect_cancels_pending_delivery_and_prevents_stale_ack():
+    now = clock.now()
+    async with session.get_identity_session() as s:
+        await store.enqueue(s, key="job", user_id=100, token="one", kind="notification", now=now)
+        row = await store.claim(s, now)
+    async with session.get_identity_session() as s:
+        await store.disconnect(s, "one")
+        await store.finish(s, row, state="sent", now=now)
+    async with session.get_identity_session() as s:
+        assert (await s.get(MaxDelivery, "job")).state == "cancelled"
+
+
+async def test_queue_survives_sessions_deduplicates_and_recovers_expired_lease():
+    now = clock.now()
+    async with session.get_identity_session() as s:
+        for _ in range(2):
+            await store.enqueue(s, key="job", user_id=100, kind="help", now=now)
+    async with session.get_identity_session() as s:
+        first = await store.claim(s, now)
+        assert first.attempts == 1
+    async with session.get_identity_session() as s:
+        assert await store.claim(s, now + timedelta(seconds=59)) is None
+    async with session.get_identity_session() as s:
+        second = await store.claim(s, now + timedelta(seconds=61))
+        assert second.id == first.id and second.lease != first.lease and second.attempts == 2
+    async with session.get_identity_session() as s:
+        await store.finish(s, first, state="sent", now=now)
+    async with session.get_identity_session() as s:
+        assert (await s.get(MaxDelivery, "job")).state == "sending"
+        await store.finish(s, second, state="sent", now=now)
+    async with session.get_identity_session() as s:
+        assert await store.claim(s, now + timedelta(days=1)) is None
+
+
+async def test_retry_deadline_and_attempt_limit():
+    now = clock.now()
+    async with session.get_identity_session() as s:
+        await store.enqueue(s, key="job", user_id=100, kind="help", now=now)
+    for attempt in range(store.MAX_ATTEMPTS):
+        when = now + timedelta(seconds=attempt * 120)
+        async with session.get_identity_session() as s:
+            row = await store.claim(s, when)
+        async with session.get_identity_session() as s:
+            await store.finish(s, row, state="queued", now=when, retry_seconds=120, error="http_429")
+        async with session.get_identity_session() as s:
+            assert await store.claim(s, when + timedelta(seconds=119)) is None
+    async with session.get_identity_session() as s:
+        assert await store.claim(s, now + timedelta(days=1)) is None
+    async with session.get_identity_session() as s:
+        row = await s.get(MaxDelivery, "job")
+        assert row.state == "failed" and row.attempts == store.MAX_ATTEMPTS
+
+
+async def test_completion_scan_ignores_old_and_incomplete_tests_and_recovers_without_duplicates():
+    now = clock.now()
+    async with session.get_clinical_session() as s:
+        await repo.upsert_profile(s, token="one", doctor_id="")
+        await repo.set_dialog_state(s, token="one", state="idle", data={"consent": True, "adult": True}, now=now)
+        for ts, complete in ((now - timedelta(days=1), True), (now, True), (now, False)):
+            s.add(ScaleResult(token="one", ts=ts, scale="phq9", total=0, severity="none", complete=complete))
+    async with session.get_identity_session() as s:
+        s.add(MaxBinding(token="one", user_id=100, enabled=True, connected_at=now))
+    for _ in range(2):
+        async with session.get_identity_session() as s:
+            await store.collect_completed(s, now)
+    async with session.get_identity_session() as s:
+        row = (await s.scalars(select(MaxDelivery))).one()
+        assert row.kind == "completed" and row.token == "one"
+        assert "phq9" not in row.id

tests/test_max_bot.py

@@ -0,0 +1,281 @@
+"""End-to-end server-only MAX flow, real SQLite transactions and mocked network."""
+
+from datetime import timedelta
+from unittest.mock import AsyncMock
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import select
+
+from app.channels import max_bot
+from app.channels.max_client import MaxApiError
+from app.config import get_settings
+from app.core import clock
+from app.db import repo, session
+from app.db.bootstrap import init_db
+from app.db.clinical import ScaleResult
+from app.db.intake import QuestionnaireRecord
+from app.db.max_notifications import MaxBinding, MaxDelivery, MaxReceipt
+from app.dialog.contracts import Reply
+from app.integrations import max_store as store
+from app.integrations.base import MemoryOutbox, integrations
+from app.main import app
+
+TOKEN = "synthetic-patient"
+SECRET = "synthetic-webhook-secret-" * 2
+
+
+@pytest.fixture(autouse=True)
+async def database(monkeypatch):
+    for key, value in {
+        "MAX_ENABLED": "true",
+        "MAX_BOT_TOKEN": "fake-token",
+        "MAX_BOT_USERNAME": "test_bot",
+        "MAX_WEBHOOK_SECRET": SECRET,
+        "MAX_WEBHOOK_URL": "https://api.example.org/api/v1/webhooks/max",
+        "MAX_SITE_URL": "https://example.org",
+    }.items():
+        monkeypatch.setenv(key, value)
+    get_settings.cache_clear()
+    max_bot.texts.cache_clear()
+    await session.configure(identity_url="sqlite+aiosqlite:///:memory:", clinical_url="sqlite+aiosqlite:///:memory:")
+    await init_db()
+    async with session.get_clinical_session() as s:
+        await repo.upsert_profile(s, token=TOKEN, doctor_id="")
+        await repo.set_dialog_state(
+            s, token=TOKEN, state="idle", data={"consent": True, "adult": True}, now=clock.now()
+        )
+    yield
+    await max_bot.stop()
+    await session.configure()
+    get_settings.cache_clear()
+
+
+def event(kind="bot_started", text="", uid=100, *, stamp=1000):
+    user = {"user_id": uid, "is_bot": False, "first_name": "Synthetic"}
+    if kind == "message_created":
+        return {
+            "update_type": kind,
+            "timestamp": stamp,
+            "message": {
+                "sender": user,
+                "recipient": {"chat_type": "dialog", "chat_id": 123},
+                "body": {"mid": f"mid-{stamp}", "text": text},
+            },
+        }
+    return {"update_type": kind, "timestamp": stamp, "user": user, "chat_id": 123, "payload": text}
+
+
+async def connect():
+    async with session.get_identity_session() as s:
+        code, _ = await store.issue_code(s, TOKEN, clock.now(), 600)
+    await max_bot.handle_update(event(text=code))
+    return code
+
+
+async def test_http_connect_webhook_duplicate_notification_and_stop():
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        auth = {"Authorization": f"Bearer {TOKEN}"}
+        linked = await client.post("/api/v1/me/notifications/max/link", headers=auth, json={"consent": True})
+        code = parse_qs(urlsplit(linked.json()["url"]).query)["start"][0]
+        headers = {"X-Max-Bot-Api-Secret": SECRET}
+        for _ in range(2):
+            assert (
+                await client.post("/api/v1/webhooks/max", headers=headers, json=event(text=code))
+            ).status_code == 200
+        assert (await client.get("/api/v1/me/notifications/max", headers=auth)).json()["connected"]
+        async with session.get_identity_session() as s:
+            assert len((await s.scalars(select(MaxReceipt))).all()) == 1
+            assert len((await s.scalars(select(MaxDelivery))).all()) == 1
+        sender = AsyncMock()
+        assert await max_bot.deliver_one(sender)
+        assert sender.send.call_args.args == (100, max_bot.texts().connected)
+        await client.post("/api/v1/webhooks/max", headers=headers, json=event("message_created", "/stop", stamp=2000))
+        assert not (await client.get("/api/v1/me/notifications/max", headers=auth)).json()["connected"]
+
+
+async def test_unbound_start_help_and_invalid_code_are_generic():
+    for e in (event(), event("message_created", "private patient text", stamp=2000), event(text="expired", stamp=3000)):
+        await max_bot.handle_update(e)
+    async with session.get_identity_session() as s:
+        rows = (await s.scalars(select(MaxDelivery))).all()
+        assert {r.kind for r in rows} == {"not_connected", "help", "invalid"}
+        assert all(r.token is None for r in rows)
+        assert not (await s.scalars(select(MaxBinding))).all()
+
+
+@pytest.mark.parametrize("kind", ["bot_stopped", "dialog_removed", "message_created"])
+async def test_stopping_cancels_pending_confirmation_and_reminders(kind):
+    await connect()
+    await max_bot.MaxOutbox(MemoryOutbox()).push(TOKEN, [Reply(text="private scheduled question")])
+    await max_bot.handle_update(event(kind, "/stop", stamp=2000))
+    async with session.get_identity_session() as s:
+        assert not (await s.get(MaxBinding, TOKEN)).enabled
+        rows = (await s.scalars(select(MaxDelivery).where(MaxDelivery.token == TOKEN))).all()
+        assert rows and all(r.state == "cancelled" for r in rows)
+    sender = AsyncMock()
+    await max_bot.deliver_one(sender)
+    assert sender.send.call_count == (1 if kind == "message_created" else 0)
+
+
+async def test_private_patient_content_stays_in_fallback_only():
+    await connect()
+    fallback = MemoryOutbox()
+    wrapper = max_bot.MaxOutbox(fallback)
+    replies = [Reply(text="SYNTHETIC confidential result 42", kind="question")]
+    await wrapper.push(TOKEN, replies)
+    await wrapper.push(TOKEN, replies)
+    assert fallback.drain(TOKEN) == replies * 2
+    async with session.get_identity_session() as s:
+        rows = (await s.scalars(select(MaxDelivery).where(MaxDelivery.kind == "notification"))).all()
+        assert len(rows) == 1
+        assert "confidential" not in repr(rows[0].__dict__)
+    sender = AsyncMock()
+    while await max_bot.deliver_one(sender):
+        pass
+    assert any(c.args[1] == max_bot.texts().notification for c in sender.send.call_args_list)
+    assert all("confidential" not in c.args[1] and TOKEN not in str(c.kwargs) for c in sender.send.call_args_list)
+
+
+async def test_revoked_consent_prevents_binding_and_delivery():
+    await connect()
+    async with session.get_clinical_session() as s:
+        await repo.set_dialog_state(
+            s, token=TOKEN, state="idle", data={"consent": False, "adult": True}, now=clock.now()
+        )
+    sender = AsyncMock()
+    await max_bot.deliver_one(sender)
+    sender.send.assert_not_called()
+    async with session.get_identity_session() as s:
+        await store.disconnect(s, TOKEN)
+        code, _ = await store.issue_code(s, TOKEN, clock.now(), 600)
+    await max_bot.handle_update(event(text=code, stamp=2000))
+    async with session.get_identity_session() as s:
+        assert not (await s.get(MaxBinding, TOKEN)).enabled
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        {},
+        {"update_type": "other", "timestamp": 1},
+        event() | {"timestamp": True},
+        event() | {"user": {"user_id": True, "is_bot": False}},
+        event() | {"user": {"user_id": 100, "is_bot": True}},
+        event() | {"payload": {"wrong": "type"}},
+        {"update_type": "message_created", "timestamp": 1, "message": {}},
+    ],
+)
+async def test_malformed_or_bot_events_are_ignored(bad):
+    await max_bot.handle_update(bad)
+    async with session.get_identity_session() as s:
+        assert not (await s.scalars(select(MaxReceipt))).all()
+
+
+async def test_group_cannot_claim_a_patient_link():
+    async with session.get_identity_session() as s:
+        code, _ = await store.issue_code(s, TOKEN, clock.now(), 600)
+    update = event("message_created", "/start " + code)
+    update["message"]["recipient"]["chat_type"] = "chat"
+    await max_bot.handle_update(update)
+    async with session.get_identity_session() as s:
+        assert await s.get(MaxBinding, TOKEN) is None
+        assert await store.code_token(s, code, clock.now()) == TOKEN
+
+
+async def test_429_respects_retry_deadline_and_then_succeeds(monkeypatch):
+    await max_bot.handle_update(event())
+    now = clock.now()
+    monkeypatch.setattr(clock, "now", lambda: now)
+    sender = AsyncMock()
+    sender.send.side_effect = MaxApiError("http_429", retryable=True, retry_after=120)
+    assert await max_bot.deliver_one(sender)
+    async with session.get_identity_session() as s:
+        row = (await s.scalars(select(MaxDelivery))).one()
+        assert row.state == "queued" and row.next_attempt_at == now + timedelta(seconds=120)
+    assert not await max_bot.deliver_one(sender)
+    now += timedelta(seconds=121)
+    sender.send.side_effect = None
+    assert await max_bot.deliver_one(sender)
+    async with session.get_identity_session() as s:
+        row = (await s.scalars(select(MaxDelivery))).one()
+        assert row.state == "sent" and row.attempts == 2
+
+
+async def test_permanent_error_does_not_retry():
+    await max_bot.handle_update(event())
+    sender = AsyncMock()
+    sender.send.side_effect = MaxApiError("http_403")
+    await max_bot.deliver_one(sender)
+    assert not await max_bot.deliver_one(sender)
+    async with session.get_identity_session() as s:
+        assert (await s.scalars(select(MaxDelivery))).one().state == "failed"
+
+
+@pytest.mark.parametrize("source", ["scale", "questionnaire"])
+async def test_completed_test_produces_one_neutral_notification(source):
+    await connect()
+    sender = AsyncMock()
+    await max_bot.deliver_one(sender)
+    sender.reset_mock()
+    async with session.get_clinical_session() as s:
+        now = clock.now()
+        if source == "scale":
+            s.add(ScaleResult(token=TOKEN, ts=now, scale="phq9", total=1, severity="synthetic", complete=True))
+        else:
+            s.add(
+                QuestionnaireRecord(
+                    id="synthetic-form",
+                    token=TOKEN,
+                    kind="intake",
+                    version="test",
+                    policy_version="test",
+                    started_at=now,
+                    completed_at=now,
+                    day=now.date(),
+                    status="complete",
+                    answers={},
+                    details={},
+                )
+            )
+    for _ in range(2):
+        async with session.get_identity_session() as s:
+            await store.collect_completed(s, clock.now())
+    assert await max_bot.deliver_one(sender)
+    assert not await max_bot.deliver_one(sender)
+    sender.send.assert_awaited_once_with(
+        100, max_bot.texts().completed, site_url="https://example.org", button=max_bot.texts().open_site
+    )
+
+
+async def test_private_start_command_accepts_issued_code():
+    async with session.get_identity_session() as s:
+        code, _ = await store.issue_code(s, TOKEN, clock.now(), 600)
+    await max_bot.handle_update(event("message_created", "/start " + code))
+    async with session.get_identity_session() as s:
+        assert (await s.get(MaxBinding, TOKEN)).user_id == 100
+
+
+async def test_disabled_lifecycle_never_constructs_client(monkeypatch):
+    monkeypatch.setenv("MAX_ENABLED", "false")
+    get_settings.cache_clear()
+    monkeypatch.setattr(max_bot, "MaxClient", lambda _: pytest.fail("disabled MAX must not create a network client"))
+    before = integrations.outbox
+    await max_bot.start()
+    await max_bot.handle_update(event())
+    await max_bot.stop()
+    assert integrations.outbox is before
+
+
+async def test_lifecycle_wraps_once_restores_and_closes(monkeypatch):
+    sender = AsyncMock()
+    monkeypatch.setattr(max_bot, "MaxClient", lambda _: sender)
+    before = integrations.outbox
+    await max_bot.start()
+    first = integrations.outbox
+    await max_bot.start()
+    assert integrations.outbox is first and first.fallback is before
+    await max_bot.stop()
+    assert integrations.outbox is before
+    sender.close.assert_awaited_once()

tests/test_max_client.py

@@ -0,0 +1,95 @@
+"""Wire contract with MAX, using an in-process HTTP fake (no real bot/token)."""
+
+import json
+import logging
+
+import httpx
+import pytest
+
+from app.channels.max_client import API_URL, UPDATE_TYPES, MaxApiError, MaxClient
+from app.config import Settings
+
+
+def settings():
+    return Settings(
+        _env_file=None,
+        max_enabled=True,
+        max_bot_token="synthetic-secret-token",
+        max_bot_username="synthetic_bot",
+        max_webhook_secret="synthetic-webhook-secret-" * 2,
+        max_webhook_url="https://api.example.org/api/v1/webhooks/max",
+        max_site_url="https://example.org",
+    )
+
+
+async def test_message_wire_contract_and_no_identifiers_in_logs(caplog):
+    def handler(request):
+        assert str(request.url).startswith(API_URL + "/messages?")
+        assert request.url.params["user_id"] == "1234567890123"
+        assert "access_token" not in request.url.params
+        assert request.headers["Authorization"] == "synthetic-secret-token"
+        body = json.loads(request.content)
+        assert body["text"] == "neutral reminder" and "format" not in body
+        button = body["attachments"][0]["payload"]["buttons"][0][0]
+        assert button == {"type": "link", "text": "Open", "url": "https://example.org"}
+        return httpx.Response(200, json={"message": {"body": {"mid": "synthetic-id"}}})
+
+    client = MaxClient(settings(), transport=httpx.MockTransport(handler))
+    with caplog.at_level(logging.INFO):
+        await client.send(1234567890123, "neutral reminder", site_url="https://example.org", button="Open")
+    await client.close()
+    assert "1234567890123" not in caplog.text and "synthetic-secret-token" not in caplog.text
+
+
+@pytest.mark.parametrize(
+    "status,retry", [(429, True), (500, True), (503, True), (408, True), (401, False), (403, False)]
+)
+async def test_error_codes_are_redacted_and_classified(status, retry):
+    client = MaxClient(
+        settings(),
+        transport=httpx.MockTransport(
+            lambda r: httpx.Response(
+                status, json={"message": "sensitive provider text"}, headers={"Retry-After": "120"}
+            )
+        ),
+    )
+    with pytest.raises(MaxApiError) as error:
+        await client.send(100, "neutral", site_url="https://example.org", button="Open")
+    assert error.value.retryable is retry and error.value.retry_after == 120
+    assert "sensitive" not in str(error.value)
+    await client.close()
+
+
+@pytest.mark.parametrize("body", [{"success": False, "message": "private"}, {}, {"success": True}, []])
+async def test_http_200_is_not_enough_to_mark_delivered(body):
+    client = MaxClient(settings(), transport=httpx.MockTransport(lambda r: httpx.Response(200, json=body)))
+    with pytest.raises(MaxApiError):
+        await client.send(100, "neutral", site_url="https://example.org", button="Open")
+    await client.close()
+
+
+async def test_timeout_is_retryable_without_request_details():
+    def handler(request):
+        raise httpx.ReadTimeout("private URL", request=request)
+
+    client = MaxClient(settings(), transport=httpx.MockTransport(handler))
+    with pytest.raises(MaxApiError, match="^transport$") as error:
+        await client.request("GET", "/me")
+    assert error.value.retryable
+    await client.close()
+
+
+async def test_subscription_includes_secret_and_exact_event_types():
+    def handler(request):
+        assert request.url.path == "/subscriptions"
+        body = json.loads(request.content)
+        assert body == {
+            "url": settings().max_webhook_url,
+            "update_types": UPDATE_TYPES,
+            "secret": settings().max_webhook_secret.get_secret_value(),
+        }
+        return httpx.Response(200, json={"success": True})
+
+    client = MaxClient(settings(), transport=httpx.MockTransport(handler))
+    await client.subscribe(settings())
+    await client.close()

tests/test_max_setup.py

@@ -0,0 +1,51 @@
+"""Operator tools do not send messages or expose credentials."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from app.channels import max_setup
+from app.channels.max_client import MaxApiError
+from app.config import Settings
+
+
+@pytest.fixture
+def client(monkeypatch):
+    settings = Settings(_env_file=None, max_bot_username="test_bot", max_webhook_url="https://api.example.org/hook")
+    sender = AsyncMock()
+    sender.request.return_value = {"is_bot": True, "username": "test_bot"}
+    monkeypatch.setattr(max_setup, "Settings", lambda **kwargs: settings)
+    monkeypatch.setattr(max_setup, "MaxClient", lambda cfg: sender)
+    return sender
+
+
+async def test_check_only_reads_bot_identity(client):
+    await max_setup.run("check")
+    client.request.assert_awaited_once_with("GET", "/me")
+    client.subscribe.assert_not_called()
+    client.send.assert_not_called()
+    client.close.assert_awaited_once()
+
+
+async def test_subscribe_is_explicit_and_checks_bot_first(client):
+    await max_setup.run("subscribe")
+    client.subscribe.assert_awaited_once()
+    client.send.assert_not_called()
+
+
+async def test_mismatched_bot_does_not_change_webhooks(client):
+    client.request.return_value = {"is_bot": True, "username": "another_bot"}
+    with pytest.raises(MaxApiError, match="bot_username_mismatch"):
+        await max_setup.run("subscribe")
+    client.subscribe.assert_not_called()
+    client.close.assert_awaited_once()
+
+
+async def test_status_checks_exact_configured_webhook(client):
+    client.request.side_effect = [
+        {"is_bot": True, "username": "test_bot"},
+        {"subscriptions": [{"url": "https://elsewhere.example.org"}]},
+    ]
+    with pytest.raises(MaxApiError, match="webhook_missing"):
+        await max_setup.run("status")
+    client.subscribe.assert_not_called()