Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

245 KB
Raw Blame
"""
API endpoint tests - auth, RBAC, pagination, security headers.

Approach: httpx.ASGITransport + dependency_overrides (no lifespan needed).
  - base_url="http://localhost" passes TrustedHostMiddleware
  - _reset_rate_limiter() clears the global limiter before each class
  - Real JWTs signed with AresSettings().secret_key_value (from ARES_SECRET_KEY env)
  - OAuth2PasswordRequestForm overridden via dependency_overrides for login tests

Note on POST body tests (register, campaigns create, change-password):
  JSON body POST endpoints return 422 via ASGITransport without lifespan because
  Starlette body parsing requires a full ASGI lifecycle. These are tested as
  integration tests in tests/integration/. Only RBAC enforcement for register
  (which returns 403 before body parsing) is tested here.
"""

from __future__ import annotations

import asyncio
import base64
import hashlib
import json
import os
from datetime import UTC, datetime, timedelta
from types import SimpleNamespace
from typing import Any
from unittest.mock import AsyncMock, MagicMock, patch

import httpx
import pytest
from fastapi import HTTPException
from fastapi.responses import JSONResponse
from fastapi.security import OAuth2PasswordRequestForm

# ── env bootstrap (before any ares import) ────────────────────────────────────
os.environ.setdefault("ARES_SECRET_KEY", "test-api-secret-key-min32-chars!!")
os.environ.setdefault("ARES_ENCRYPTION_KEY", "test-enc-key-min32-chars-xxxxxxx")
os.environ.setdefault("ARES_DEFAULT_ADMIN_PASSWORD", "TestApiPass1!")
os.environ.setdefault("ARES_DEBUG", "true")
os.environ.setdefault("ARES_BROWSER_ORIGIN", "http://localhost:5173")


# ── helpers ───────────────────────────────────────────────────────────────────


_MOCK_PRINCIPAL_ROLES: dict[str, str] = {}
_C_LIVE_TEST_KEY = "11111111-1111-4111-8111-111111111111"
_PRODUCTION_C_LIVE_DESCRIPTOR_GATE: Any = None


def _settings():
    from ares.core.config import AresSettings

    return AresSettings()


def _make_token(username: str, role: str) -> str:
    from ares.core.security import create_access_token

    _MOCK_PRINCIPAL_ROLES[username] = role
    s = _settings()
    family_id = base64.urlsafe_b64encode(
        hashlib.sha256(username.encode("utf-8")).digest()
    ).rstrip(b"=").decode("ascii")
    return create_access_token(
        data={"sub": username, "sid": family_id, "ver": 1},
        secret_key=s.secret_key_value,
        expires_minutes=60,
    )


def _auth(username: str, role: str) -> dict:
    return {
        "Authorization": f"Bearer {_make_token(username, role)}",
        "Idempotency-Key": _C_LIVE_TEST_KEY,
    }


class _UnitLiveCoordinator:
    def __init__(self, engine: Any, role: str) -> None:
        self._engine = engine
        self._role = role

    async def execute_module(self, principal: Any, request: Any, campaign: Any) -> Any:
        del principal
        from ares.core.execution_admission import (
            DispatchDispositionV1,
            DispatchOutcomeV1,
            _identity,
        )
        from ares.db.execution_lifecycle import FixedResult

        result = await self._engine.run_module(
            request.module_id,
            campaign,
            dict(request.raw_parameters),
            actor_role=self._role,
        )
        return DispatchOutcomeV1(
            DispatchDispositionV1.TERMINAL,
            _identity(request),
            FixedResult.APPLIED,
            4,
            result,
            True,
            True,
        )


class _UnitLiveRuntime:
    def __init__(self, app: Any) -> None:
        self._app = app

    def bind(self, actor: Any) -> tuple[Any, _UnitLiveCoordinator]:
        from ares.api.server import get_engine
        from ares.db.execution_lifecycle import TrustedPrincipal

        provider = self._app.dependency_overrides.get(get_engine)
        engine = provider() if provider is not None else self._app.state.engine
        source = actor.websocket_ticket_source
        principal = TrustedPrincipal(source.user_id, source.user_id)
        return principal, _UnitLiveCoordinator(engine, actor.role)


def _c_live_result(module_id: str = "plugin.safe") -> Any:
    result = SimpleNamespace(
        module_id=module_id,
        status="done",
        findings=[],
        error="",
        duration_ms=1.0,
    )
    result.model_dump = lambda: {
        "module_id": module_id,
        "status": "done",
        "findings": [],
        "validation_results": [],
        "raw_output": {},
        "error": "",
        "duration_ms": 1.0,
    }
    return result


class _RecordingLiveCoordinator:
    def __init__(self, outcome_factory: Any = None) -> None:
        self.requests: list[Any] = []
        self.principals: list[Any] = []
        self._outcome_factory = outcome_factory

    async def execute_module(self, principal: Any, request: Any, campaign: Any) -> Any:
        del campaign
        from ares.core.execution_admission import (
            DispatchDispositionV1,
            DispatchOutcomeV1,
            _identity,
        )
        from ares.db.execution_lifecycle import FixedResult

        self.principals.append(principal)
        self.requests.append(request)
        if self._outcome_factory is not None:
            return self._outcome_factory(request)
        return DispatchOutcomeV1(
            DispatchDispositionV1.TERMINAL,
            _identity(request),
            FixedResult.APPLIED,
            4,
            _c_live_result(request.module_id),
            True,
            True,
        )


class _RecordingLiveRuntime:
    def __init__(self, coordinator: _RecordingLiveCoordinator) -> None:
        self.coordinator = coordinator

    def bind(self, actor: Any) -> tuple[Any, _RecordingLiveCoordinator]:
        from ares.db.execution_lifecycle import TrustedPrincipal

        source = actor.websocket_ticket_source
        return TrustedPrincipal(source.user_id, source.user_id), self.coordinator


def _nonterminal_outcome(result: Any, disposition: Any) -> Any:
    from ares.core.execution_admission import (
        DispatchIdentityV1,
        DispatchOutcomeV1,
    )

    identity = DispatchIdentityV1(
        "10000000-0000-4000-8000-000000000001",
        "10000000-0000-4000-8000-000000000002",
        "10000000-0000-4000-8000-000000000003",
        "10000000-0000-4000-8000-000000000004",
        "10000000-0000-4000-8000-000000000005",
        "10000000-0000-4000-8000-000000000006",
        "10000000-0000-4000-8000-000000000007",
        "10000000-0000-4000-8000-000000000008",
    )
    return DispatchOutcomeV1(
        disposition,
        identity,
        result,
        0,
        None,
        disposition.value == "indeterminate",
        False,
    )


def _issued_session(username: str = "admin", role: str = "team_lead"):
    from ares.core.security import create_access_token
    from ares.core.token_sessions import (
        IssuedTokenSession,
        SessionIssueResult,
        SessionIssueStatus,
    )

    family_id = base64.urlsafe_b64encode(
        hashlib.sha256(username.encode("utf-8")).digest()
    ).rstrip(b"=").decode("ascii")
    token = create_access_token(
        {"sub": username, "sid": family_id, "ver": 1},
        _settings().secret_key_value,
    )
    return SessionIssueResult(
        SessionIssueStatus.ISSUED,
        IssuedTokenSession(
            access_token=token,
            refresh_token="r" * 64,  # noqa: S106 - fixed test value
            user_id="test-user-id",
            subject=username,
            family_id=family_id,
            auth_epoch=1,
            absolute_expires_at=datetime.now(UTC) + timedelta(days=30),
            refresh_generation=0,
            role=role,
        ),
    )


def _api_key_headers(raw_key: str = "ares_test_api_key") -> dict:
    return {"X-API-Key": raw_key}


def _api_key_record(
    scopes: str | list[str],
    *,
    username: str = "admin",
    role: str = "team_lead",
    key_id: str = "api-key-1",
) -> dict[str, Any]:
    scope_list = [scopes] if isinstance(scopes, str) else scopes
    return {
        "username": username,
        "role": role,
        "auth_type": "api_key",
        "key_id": key_id,
        "scopes": scope_list,
    }


def _make_mock_db():
    from ares.core.token_sessions import (
        RefreshRotationResult,
        RefreshRotationStatus,
        SessionIssueResult,
        SessionIssueStatus,
        SessionRevocationResult,
        SessionRevocationStatus,
    )

    db = MagicMock()
    db.verify_user = AsyncMock(return_value=None)
    db.get_user = AsyncMock(return_value=None)
    db.user_exists = AsyncMock(return_value=False)
    db.create_user = AsyncMock()
    db.create_refresh_token = AsyncMock(return_value="mock-refresh-token")
    db.rotate_refresh_token = AsyncMock(return_value=(None, None))
    db.revoke_all_refresh_tokens = AsyncMock()
    db.revoke_access_token = AsyncMock()
    db.is_access_token_revoked = AsyncMock(return_value=False)
    db.create_login_session = AsyncMock(
        return_value=SessionIssueResult(SessionIssueStatus.INVALID)
    )
    db.rotate_refresh_session = AsyncMock(
        return_value=RefreshRotationResult(RefreshRotationStatus.INVALID)
    )
    db.revoke_current_session = AsyncMock(
        return_value=SessionRevocationResult(SessionRevocationStatus.REVOKED)
    )
    db.revoke_refresh_cookie_session = AsyncMock(
        return_value=SessionRevocationResult(SessionRevocationStatus.REVOKED)
    )
    db.revoke_all_sessions = AsyncMock(
        return_value=SessionRevocationResult(SessionRevocationStatus.REVOKED)
    )
    db.apply_user_security_event = AsyncMock(return_value=True)

    async def resolve_access_token_principal(
        subject: str,
        _jti: str,
        _family_id: str,
        auth_epoch: int,
    ) -> dict[str, str] | None:
        if db.is_access_token_revoked.return_value is True:
            return None
        role = _MOCK_PRINCIPAL_ROLES.get(subject)
        if role is None:
            return None
        return {
            "id": f"mock-user-{subject}",
            "username": subject,
            "role": role,
            "auth_epoch": auth_epoch,
        }

    db.resolve_access_token_principal = AsyncMock(
        side_effect=resolve_access_token_principal
    )
    db.audit = AsyncMock()
    db.purge_expired_tokens = AsyncMock(return_value=0)
    db.list_campaigns = AsyncMock(return_value=([], 0))
    db.get_campaign = AsyncMock(return_value=None)
    db.list_findings = AsyncMock(return_value=([], 0))
    db.get_monthly_confirmed_finding_stats = AsyncMock(
        return_value={
            "period": "2026-07",
            "label": "Security signals this cycle",
            "total": 0,
            "confirmed_findings": 0,
            "series": [],
        }
    )
    db.record_module_run = AsyncMock()
    db.get_telemetry_stats = AsyncMock(
        return_value={
            "modules": {"total": 0, "success": 0, "failed": 0, "error_rate": 0.0},
            "findings": 0,
            "latency_ms": {"p50": None, "p95": None, "p99": None},
            "throughput": {"tasks_per_min": None},
            "hosts": {"available": False, "discovered": 0, "owned": None},
        }
    )
    db.delete_campaign = AsyncMock(return_value=False)
    db.verify_api_key = AsyncMock(return_value=None)
    db.issue_websocket_ticket = AsyncMock(return_value=None)
    db.consume_websocket_ticket = AsyncMock(return_value=None)
    db.resolve_websocket_ticket_principal = AsyncMock(return_value=None)
    return db


def _reset_rate_limiter() -> None:
    """Clear global in-process rate limiter to prevent cross-test bleed."""
    from ares.api.rbac import _limiter

    _limiter._windows.clear()


def _run(coro):
    """Run a coroutine in a new event loop (for sync pytest methods)."""
    return asyncio.get_event_loop().run_until_complete(coro)


def _require_fixed(condition: bool, message: str) -> None:
    if not condition:
        pytest.fail(message, pytrace=False)


# ── shared async client ───────────────────────────────────────────────────────


@pytest.mark.parametrize(
    ("outcome", "expected"),
    [
        ("modulestatus.done", True),
        ("done", True),
        ("success", True),
        ("partial", True),
        ("confirmed_findings", True),
        ("completed_no_findings", True),
        ("dry_run_ok", True),
        ("failed", False),
        ("error", False),
        ("module_error", False),
        ("operator_error", False),
        ("dependency_error", False),
        ("network_error", False),
        ("timeout", False),
        ("unsupported", False),
    ],
)
def test_module_outcome_success_mapping(outcome: str, expected: bool) -> None:
    from ares.api.server import _is_successful_module_outcome

    assert _is_successful_module_outcome(outcome) is expected


@pytest.fixture(scope="module", autouse=True)
def _app_mock_db():
    global _PRODUCTION_C_LIVE_DESCRIPTOR_GATE
    # Clear lru_cache so unit tests always use UNIT env vars,
    # not a cached instance from a previous integration test run.
    from ares.core.config import get_settings as _get_settings_fn

    _get_settings_fn.cache_clear()

    import ares.api.server as _server
    from ares.api.server import app as _app
    from ares.api.server import get_c_live_runtime, get_db, get_settings
    from ares.core.config import AresSettings

    mock_db = _make_mock_db()
    fake_settings = AresSettings()

    # Set app.state.db for endpoints that read it directly (e.g. /health)
    _app.state.db = mock_db

    _app.dependency_overrides[get_db] = lambda: mock_db
    _app.dependency_overrides[get_settings] = lambda: fake_settings
    _app.dependency_overrides[get_c_live_runtime] = lambda: _UnitLiveRuntime(_app)
    original_descriptor_gate = _server._c_live_descriptor_gate
    _PRODUCTION_C_LIVE_DESCRIPTOR_GATE = original_descriptor_gate
    _server._c_live_descriptor_gate = lambda _module_id, _role: None

    yield _app, mock_db

    _server._c_live_descriptor_gate = original_descriptor_gate
    _app.dependency_overrides.clear()
    # Clear cache again so the next test module starts fresh
    _get_settings_fn.cache_clear()


@pytest.fixture(scope="module")
def aclient(_app_mock_db):
    """Async same-origin browser client with a rotating CSRF header."""
    _app, mock_db = _app_mock_db
    transport = httpx.ASGITransport(app=_app)
    client: httpx.AsyncClient

    async def _browser_headers(request: httpx.Request) -> None:
        if request.url.path in {
            "/auth/token",
            "/auth/refresh",
            "/auth/logout",
            "/auth/logout-all",
        }:
            request.headers["Origin"] = "http://localhost:5173"
            request.headers["Sec-Fetch-Site"] = "same-origin"
            try:
                csrf = client.cookies.get("ares-dev-csrf")
            except httpx.CookieConflict:
                csrf = None
            csrf = csrf or ("A" * 43)
            request.headers["X-ARES-CSRF"] = csrf
            cookie = request.headers.get("Cookie", "")
            if "ares-dev-csrf=" not in cookie:
                request.headers["Cookie"] = (
                    f"{cookie}; ares-dev-csrf={csrf}" if cookie else f"ares-dev-csrf={csrf}"
                )

    client = httpx.AsyncClient(
        transport=transport,
        base_url="http://localhost:5173",
        event_hooks={"request": [_browser_headers]},
    )
    client.cookies.set(
        "ares-dev-csrf", "A" * 43, domain="localhost.local", path="/"
    )
    yield client, mock_db, _app
    asyncio.run(client.aclose())


@pytest.fixture
def c_live_route(aclient: Any) -> Any:
    """Install one request-local fake admission runtime without changing production."""
    from ares.api.server import get_c_live_runtime, get_engine

    client, db, app = aclient
    original_engine = app.dependency_overrides.get(get_engine)
    original_runtime = app.dependency_overrides.get(get_c_live_runtime)
    original_resolver_side_effect = db.resolve_access_token_principal.side_effect
    original_resolver_return = db.resolve_access_token_principal.return_value
    engine = SimpleNamespace(
        registry=MagicMock(),
        run_module=AsyncMock(return_value=_c_live_result()),
        run_plan=AsyncMock(),
        dry_run_module=MagicMock(
            return_value={"status": "dry_run_ok", "module_id": "plugin.safe"}
        ),
        dry_run_plan=MagicMock(
            return_value={"status": "dry_run_ok", "modules": [], "would_execute": True}
        ),
    )
    app.dependency_overrides[get_engine] = lambda: engine
    db.is_access_token_revoked.return_value = False
    db.get_campaign.side_effect = None
    db.get_campaign.return_value = {
        "id": "camp-c-live",
        "name": "C-LIVE",
        "client": "Internal",
        "operator": "legacy-username-must-not-authorize",
        "noise_profile": "normal",
        "status": "created",
        "scope_json": "[]",
        "targets_json": "[]",
        "notes": "",
    }

    def install(coordinator: _RecordingLiveCoordinator) -> None:
        app.dependency_overrides[get_c_live_runtime] = lambda: _RecordingLiveRuntime(
            coordinator
        )

    install(_RecordingLiveCoordinator())
    try:
        yield client, db, app, engine, install
    finally:
        db.is_access_token_revoked.return_value = False
        db.resolve_access_token_principal.side_effect = original_resolver_side_effect
        db.resolve_access_token_principal.return_value = original_resolver_return
        if original_engine is None:
            app.dependency_overrides.pop(get_engine, None)
        else:
            app.dependency_overrides[get_engine] = original_engine
        if original_runtime is None:
            app.dependency_overrides.pop(get_c_live_runtime, None)
        else:
            app.dependency_overrides[get_c_live_runtime] = original_runtime


# ── Health ────────────────────────────────────────────────────────────────────


class TestHealthEndpoint:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_health_returns_200(self, aclient):
        c, _, __ = aclient
        r = await c.get("/health")
        assert r.status_code == 200

    @pytest.mark.asyncio
    async def test_health_has_status_ok(self, aclient):
        c, _, __ = aclient
        r = await c.get("/health")
        assert r.json().get("status") in ("ok", "degraded", "healthy")

    @pytest.mark.asyncio
    async def test_health_has_version(self, aclient):
        c, _, __ = aclient
        r = await c.get("/health")
        assert "version" in r.json()


class TestMonthlyStatsEndpoint:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_monthly_stats_returns_confirmed_finding_series(self, aclient):
        c, db, _ = aclient
        expected = {
            "period": "2026-07",
            "label": "Security signals this cycle",
            "total": 2,
            "confirmed_findings": 2,
            "series": [{"date": "2026-07-18", "count": 2}],
        }
        db.get_monthly_confirmed_finding_stats.return_value = expected

        response = await c.get("/stats/monthly", headers=_auth("admin", "team_lead"))

        assert response.status_code == 200
        assert response.json() == expected
        db.get_monthly_confirmed_finding_stats.assert_awaited_once_with()

    @pytest.mark.asyncio
    async def test_monthly_stats_filters_by_campaign_id(self, aclient):
        c, db, _ = aclient
        db.get_monthly_confirmed_finding_stats.reset_mock()
        expected = {
            "period": "2026-07",
            "label": "Security signals this cycle",
            "total": 1,
            "confirmed_findings": 1,
            "series": [{"date": "2026-07-18", "count": 1}],
        }
        db.get_monthly_confirmed_finding_stats.return_value = expected

        response = await c.get(
            "/stats/monthly?campaign_id=camp-target-123",
            headers=_auth("admin", "team_lead"),
        )

        assert response.status_code == 200
        assert response.json() == expected
        db.get_monthly_confirmed_finding_stats.assert_awaited_once_with(
            campaign_id="camp-target-123"
        )


# ── Security headers ──────────────────────────────────────────────────────────


class TestSecurityHeaders:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_x_frame_options_deny(self, aclient):
        c, _, __ = aclient
        assert (await c.get("/health")).headers.get("x-frame-options") == "DENY"

    @pytest.mark.asyncio
    async def test_x_content_type_nosniff(self, aclient):
        c, _, __ = aclient
        assert (await c.get("/health")).headers.get(
            "x-content-type-options"
        ) == "nosniff"

    @pytest.mark.asyncio
    async def test_cache_control_no_store(self, aclient):
        c, _, __ = aclient
        assert "no-store" in (await c.get("/health")).headers.get("cache-control", "")

    @pytest.mark.asyncio
    async def test_server_header_stripped(self, aclient):
        c, _, __ = aclient
        hdrs = {k.lower() for k in (await c.get("/health")).headers}
        assert "server" not in hdrs

    @pytest.mark.asyncio
    async def test_cors_is_exact_and_never_credentialed(self, aclient):
        c, _, __ = aclient
        allowed = await c.options(
            "/health",
            headers={
                "Origin": "http://localhost:3000",
                "Access-Control-Request-Method": "GET",
            },
        )
        denied = await c.options(
            "/health",
            headers={
                "Origin": "https://untrusted.example",
                "Access-Control-Request-Method": "GET",
            },
        )
        reduced = (
            allowed.headers.get("access-control-allow-origin")
            == "http://localhost:3000",
            "access-control-allow-credentials" not in allowed.headers,
            denied.headers.get("access-control-allow-origin") is None,
            "access-control-allow-credentials" not in denied.headers,
        )
        _require_fixed(all(reduced), "CORS credential boundary differed")


# ── Auth flow ─────────────────────────────────────────────────────────────────


class TestAuthFlow:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_me_without_token_returns_401(self, aclient):
        c, _, __ = aclient
        assert (await c.get("/auth/me")).status_code == 401

    @pytest.mark.asyncio
    async def test_me_with_bad_token_returns_401(self, aclient):
        c, _, __ = aclient
        r = await c.get("/auth/me", headers={"Authorization": "Bearer not.a.valid.jwt"})
        assert r.status_code == 401

    @pytest.mark.asyncio
    async def test_me_with_valid_token_returns_user(self, aclient):
        c, db, _ = aclient
        _reset_rate_limiter()
        db.is_access_token_revoked.return_value = False
        r = await c.get("/auth/me", headers=_auth("admin", "team_lead"))
        assert r.status_code == 200
        assert r.json().get("username") == "admin"
        assert r.json().get("role") == "team_lead"

    @pytest.mark.asyncio
    async def test_csrf_bootstrap_is_empty_uncacheable_and_cookie_only(self, aclient):
        c, _, __ = aclient
        response = await c.get("/auth/csrf")
        cookie_headers = response.headers.get_list("set-cookie")
        reduced = (
            response.status_code == 204,
            response.content == b"",
            response.headers.get("cache-control") == "no-store",
            response.headers.get("pragma") == "no-cache",
            len(cookie_headers) == 1,
            cookie_headers[0].startswith("ares-dev-csrf=") if cookie_headers else False,
            "httponly" not in cookie_headers[0].lower() if cookie_headers else False,
            "max-age=600" in cookie_headers[0].lower() if cookie_headers else False,
        )
        del cookie_headers
        _require_fixed(all(reduced), "CSRF bootstrap contract differed")

    @pytest.mark.asyncio
    async def test_login_invalid_credentials_returns_401(self, aclient):
        """Login with mocked OAuth2PasswordRequestForm - invalid creds → 401."""
        c, db, _app = aclient
        _reset_rate_limiter()
        db.verify_user.return_value = None

        class FakeForm:
            username = "hacker"
            password = "wrong"  # noqa: S105 - test fixture credential
            scopes = []
            client_id = None
            client_secret = None

        _app.dependency_overrides[OAuth2PasswordRequestForm] = lambda: FakeForm()
        try:
            r = await c.post("/auth/token")
            assert r.status_code == 401
        finally:
            del _app.dependency_overrides[OAuth2PasswordRequestForm]

    @pytest.mark.asyncio
    async def test_login_valid_credentials_returns_tokens(self, aclient):
        """Login with mocked OAuth2PasswordRequestForm - valid creds → 200 + tokens."""
        c, db, _app = aclient
        _reset_rate_limiter()
        db.create_login_session.return_value = _issued_session()

        class FakeForm:
            username = "admin"
            password = "correct"  # noqa: S105 - test fixture credential
            scopes = []
            client_id = None
            client_secret = None

        _app.dependency_overrides[OAuth2PasswordRequestForm] = lambda: FakeForm()
        try:
            r = await c.post("/auth/token")
            assert r.status_code == 200
            body = r.json()
            assert "access_token" in body
            assert "refresh_token" not in body
            assert body["token_type"] == "bearer"  # noqa: S105 - OAuth token type
            cookie_headers = r.headers.get_list("set-cookie")
            reduced = (
                len(cookie_headers) == 2,
                any(value.startswith("ares-dev-refresh=") for value in cookie_headers),
                any(value.startswith("ares-dev-csrf=") for value in cookie_headers),
                sum("httponly" in value.lower() for value in cookie_headers) == 1,
                all("samesite=strict" in value.lower() for value in cookie_headers),
                all("path=/" in value.lower() for value in cookie_headers),
                all("domain=" not in value.lower() for value in cookie_headers),
            )
            del cookie_headers
            _require_fixed(all(reduced), "Committed login cookie contract differed")
        finally:
            del _app.dependency_overrides[OAuth2PasswordRequestForm]
            db.create_login_session.return_value = None

    @pytest.mark.asyncio
    async def test_unauthenticated_endpoint_returns_401(self, aclient):
        c, _, __ = aclient
        assert (await c.get("/campaigns/any-id")).status_code == 401

    @pytest.mark.asyncio
    async def test_inactive_api_key_uses_generic_failure_without_endpoint_work(
        self, aclient
    ):
        """Response/handler mapping; real SQLite containment is covered below."""
        c, db, _ = aclient
        _reset_rate_limiter()
        db.verify_api_key.return_value = None
        db.verify_api_key.reset_mock()
        db.list_campaigns.reset_mock()

        response = await c.get("/campaigns", headers=_api_key_headers())
        response_body = response.json()
        generic_failure = (
            response_body.get("code") == 401
            and response_body.get("detail")
            == "Not authenticated. Provide Bearer token or X-API-Key."
            and response_body.get("type") == "api_error"
        )
        if not (
            response.status_code == 401
            and generic_failure
            and db.verify_api_key.await_count == 1
            and db.list_campaigns.await_count == 0
        ):
            pytest.fail(
                "expected inactive API key to fail generically before endpoint work",
                pytrace=False,
            )
        if "inactive" in response.text.lower():
            pytest.fail(
                "expected API-key authentication failure not to disclose account status",
                pytrace=False,
            )

    @pytest.mark.asyncio
    async def test_inactive_refresh_uses_generic_failure_without_successor(
        self, aclient
    ):
        """Response/handler mapping; real SQLite containment is covered below."""
        c, db, _ = aclient
        _reset_rate_limiter()
        db.rotate_refresh_session.reset_mock()
        db.create_refresh_token.reset_mock()
        c.cookies.set(
            "ares-dev-refresh", "r" * 64, domain="localhost.local", path="/"
        )

        response = await c.post("/auth/refresh")
        response_body = response.json()
        generic_failure = (
            response_body.get("code") == 401
            and response_body.get("detail") == "Session is not valid"
            and response_body.get("type") == "api_error"
        )
        _require_fixed(response.status_code == 401, "inactive refresh status differed")
        _require_fixed(generic_failure, "inactive refresh detail differed")
        _require_fixed(
            db.rotate_refresh_session.await_count == 1,
            "inactive refresh lookup count differed",
        )
        _require_fixed(
            db.create_refresh_token.await_count == 0,
            "inactive refresh created successor",
        )
        if "inactive" in response.text.lower():
            pytest.fail(
                "expected refresh authentication failure not to disclose account status",
                pytrace=False,
            )

    @pytest.mark.asyncio
    async def test_refresh_json_transport_is_rejected_before_database(self, aclient):
        c, db, _ = aclient
        _reset_rate_limiter()
        db.rotate_refresh_session.reset_mock()
        c.cookies.set(
            "ares-dev-csrf", "A" * 43, domain="localhost.local", path="/"
        )
        response = await c.post(
            "/auth/refresh",
            json={"refresh_token": "legacy-transport"},
        )
        _require_fixed(response.status_code == 400, "legacy refresh body was accepted")
        _require_fixed(db.rotate_refresh_session.await_count == 0, "legacy body reached database")

    @pytest.mark.asyncio
    async def test_refresh_backend_uncertainty_publishes_no_cookie(self, aclient):
        c, db, _ = aclient
        _reset_rate_limiter()
        c.cookies.set(
            "ares-dev-refresh", "r" * 64, domain="localhost.local", path="/"
        )
        db.rotate_refresh_session.side_effect = RuntimeError("fixed-test-canary")
        try:
            response = await c.post("/auth/refresh")
            reduced = (
                response.status_code == 503,
                not response.headers.get_list("set-cookie"),
            )
            _require_fixed(all(reduced), "Indeterminate refresh published browser state")
        finally:
            db.rotate_refresh_session.side_effect = None

    @pytest.mark.asyncio
    async def test_cookie_logout_commits_then_clears_exact_cookies(self, aclient):
        c, db, _ = aclient
        _reset_rate_limiter()
        c.cookies.set(
            "ares-dev-refresh", "r" * 64, domain="localhost.local", path="/"
        )
        db.revoke_refresh_cookie_session.reset_mock()
        response = await c.post("/auth/logout")
        cookie_headers = response.headers.get_list("set-cookie")
        reduced = (
            response.status_code == 204,
            response.content == b"",
            db.revoke_refresh_cookie_session.await_count == 1,
            len(cookie_headers) == 2,
            all("max-age=0" in value.lower() for value in cookie_headers),
            all("path=/" in value.lower() for value in cookie_headers),
            all("samesite=strict" in value.lower() for value in cookie_headers),
            all("domain=" not in value.lower() for value in cookie_headers),
        )
        del cookie_headers
        _require_fixed(all(reduced), "Cookie logout contract differed")

    @pytest.mark.asyncio
    async def test_real_sqlite_inactive_credentials_fail_at_api_boundary(
        self,
        aclient,
        tmp_path,
        monkeypatch,
    ):
        c, _, app = aclient
        from ares.api.server import get_db
        from ares.db.database import AresDatabase

        real_db = await AresDatabase.create(tmp_path / "inactive-boundary.db")
        original_app_db = getattr(app.state, "db", None)
        no_override = object()
        original_override = app.dependency_overrides.get(get_db, no_override)
        handler_calls = [0]
        original_list_campaigns = real_db.list_campaigns

        async def counted_list_campaigns(*args, **kwargs):
            handler_calls[0] += 1
            return await original_list_campaigns(*args, **kwargs)

        with monkeypatch.context() as patch:
            patch.setattr(real_db, "list_campaigns", counted_list_campaigns)
            app.state.db = real_db
            app.dependency_overrides[get_db] = lambda: real_db
            try:
                user_id = await real_db.create_user(
                    "inactive-boundary-user",
                    "SyntheticBoundaryPass1!",
                    "operator",
                )
                key_id, raw_key = await real_db.create_api_key(
                    user_id,
                    "inactive-boundary-key",
                )
                refresh_token = await real_db.create_refresh_token(user_id)
                async with real_db.conn.execute(
                    "SELECT id FROM refresh_tokens WHERE user_id=?",
                    (user_id,),
                ) as cur:
                    original_refresh_row = await cur.fetchone()
                original_refresh_id = (
                    original_refresh_row["id"]
                    if original_refresh_row is not None
                    else None
                )

                active_response = await c.get(
                    "/campaigns",
                    headers={"X-API-Key": raw_key},
                )
                active_control = (
                    active_response.status_code == 200 and handler_calls[0] == 1
                )
                _require_fixed(
                    active_control,
                    "expected active real SQLite API key to reach protected work",
                )

                usage_marker = "2000-01-01 00:00:00"
                await real_db.conn.execute(
                    "UPDATE api_keys SET last_used=? WHERE id=?",
                    (usage_marker, key_id),
                )
                await real_db.conn.execute(
                    "UPDATE users SET is_active=0 WHERE id=?",
                    (user_id,),
                )
                await real_db.conn.commit()
                handler_calls[0] = 0

                api_response = await c.get(
                    "/campaigns",
                    headers={"X-API-Key": raw_key},
                )
                c.cookies.set(
                    "ares-dev-csrf", "A" * 43,
                    domain="localhost.local", path="/",
                )
                c.cookies.set(
                    "ares-dev-refresh", refresh_token,
                    domain="localhost.local", path="/",
                )
                refresh_response = await c.post("/auth/refresh")

                api_body = api_response.json()
                refresh_body = refresh_response.json()
                api_contract = (
                    api_response.status_code == 401
                    and api_body.get("detail")
                    == "Not authenticated. Provide Bearer token or X-API-Key."
                    and "inactive" not in api_response.text.lower()
                    and handler_calls[0] == 0
                )
                refresh_contract = (
                    refresh_response.status_code == 401
                    and refresh_body.get("detail") == "Session is not valid"
                    and "inactive" not in refresh_response.text.lower()
                    and "refresh_token" not in refresh_body
                )

                async with real_db.conn.execute(
                    "SELECT last_used FROM api_keys WHERE id=?",
                    (key_id,),
                ) as cur:
                    api_key_row = await cur.fetchone()
                async with real_db.conn.execute(
                    """SELECT id, user_id, is_revoked, used_at
                       FROM refresh_tokens
                       WHERE user_id=?""",
                    (user_id,),
                ) as cur:
                    refresh_rows = await cur.fetchall()

                usage_unchanged = (
                    api_key_row is not None
                    and api_key_row["last_used"] == usage_marker
                )
                predecessor_unchanged = (
                    len(refresh_rows) == 1
                    and original_refresh_id is not None
                    and refresh_rows[0]["id"] == original_refresh_id
                    and refresh_rows[0]["user_id"] == user_id
                    and refresh_rows[0]["is_revoked"] == 0
                    and refresh_rows[0]["used_at"] is None
                )
                _require_fixed(
                    api_contract,
                    "expected inactive real SQLite API key to fail generically",
                )
                _require_fixed(
                    refresh_contract,
                    "expected inactive real SQLite refresh to fail generically",
                )
                _require_fixed(
                    usage_unchanged,
                    "expected inactive API-key usage metadata to remain unchanged",
                )
                _require_fixed(
                    predecessor_unchanged,
                    "expected inactive refresh predecessor to remain unchanged",
                )
            finally:
                app.state.db = original_app_db
                if original_override is no_override:
                    app.dependency_overrides.pop(get_db, None)
                else:
                    app.dependency_overrides[get_db] = original_override
                await real_db.close()


# ── RBAC enforcement ──────────────────────────────────────────────────────────


class TestAPIKeyScopeEnforcement:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_api_key_identity_preserves_metadata(self, aclient):
        _, db, _ = aclient
        from ares.api.server import get_current_user_or_apikey

        db.verify_api_key.return_value = _api_key_record(["read", "write"])
        request = SimpleNamespace(
            headers=_api_key_headers(),
            app=SimpleNamespace(state=SimpleNamespace(db=db)),
        )

        actor = await get_current_user_or_apikey(request, bearer=None)

        assert actor.username == "admin"
        assert actor.role == "team_lead"
        assert actor.auth_type == "api_key"
        assert actor.is_api_key
        assert actor.api_key_id == "api-key-1"
        assert actor.api_key_scopes == ("read", "write")

    @pytest.mark.asyncio
    async def test_read_scoped_api_key_cannot_generate_report(self, aclient):
        c, db, _ = aclient
        db.verify_api_key.return_value = _api_key_record("read")
        db.get_campaign.reset_mock()

        r = await c.post("/reports/camp-api-key", headers=_api_key_headers())

        assert r.status_code == 403
        db.get_campaign.assert_not_called()

    @pytest.mark.asyncio
    async def test_write_scoped_api_key_can_generate_report_when_campaign_access_allows(
        self, aclient, tmp_path, monkeypatch
    ):
        c, db, _ = aclient
        import ares.modules.reporting.report_gen as report_gen

        db.verify_api_key.return_value = _api_key_record("write")
        db.audit.reset_mock()
        db.get_campaign.return_value = {
            "id": "camp-api-key",
            "name": "API Key Campaign",
            "client": "Internal",
            "operator": "admin",
            "targets": [],
            "scope": [],
        }

        class FakeReportGenerator:
            def __init__(self, *args, **kwargs):
                pass

            def generate(self, campaign, fmt="html"):
                path = tmp_path / f"{campaign.id}_report.{fmt}"
                path.write_text("report", encoding="utf-8")
                return path

        monkeypatch.setattr(report_gen, "ReportGenerator", FakeReportGenerator)

        r = await c.post(
            "/reports/camp-api-key?fmt=html",
            headers=_api_key_headers(),
        )

        assert r.status_code == 200
        assert r.json()["filename"] == "camp-api-key_report.html"
        db.audit.assert_awaited()

    @pytest.mark.asyncio
    async def test_write_scoped_api_key_does_not_bypass_campaign_access(self, aclient):
        c, db, _ = aclient
        db.verify_api_key.return_value = _api_key_record(
            "write", username="reporter_user", role="reporter"
        )
        db.get_campaign.return_value = {
            "id": "camp-api-key",
            "name": "API Key Campaign",
            "operator": "admin",
        }

        r = await c.post(
            "/reports/camp-api-key?fmt=html",
            headers=_api_key_headers(),
        )

        assert r.status_code == 404

    @pytest.mark.asyncio
    async def test_jwt_auth_generate_report_unchanged(
        self, aclient, tmp_path, monkeypatch
    ):
        c, db, _ = aclient
        import ares.modules.reporting.report_gen as report_gen

        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-jwt",
            "name": "JWT Campaign",
            "client": "Internal",
            "operator": "admin",
            "targets": [],
            "scope": [],
        }

        class FakeReportGenerator:
            def __init__(self, *args, **kwargs):
                pass

            def generate(self, campaign, fmt="html"):
                path = tmp_path / f"{campaign.id}_report.{fmt}"
                path.write_text("report", encoding="utf-8")
                return path

        monkeypatch.setattr(report_gen, "ReportGenerator", FakeReportGenerator)

        r = await c.post(
            "/reports/camp-jwt?fmt=html",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 200
        assert r.json()["filename"] == "camp-jwt_report.html"

    @pytest.mark.parametrize(
        ("method", "path", "kwargs"),
        [
            (
                "post",
                "/auth/change-password",
                {
                    "json": {
                        "current_password": "CurrentPassword123!",
                        "new_password": "NewPassword123!",
                    }
                },
            ),
            (
                "post",
                "/auth/api-keys",
                {"json": {"name": "ci", "scopes": "admin"}},
            ),
            ("get", "/auth/api-keys", {}),
            ("delete", "/auth/api-keys/api-key-1", {}),
        ],
    )
    @pytest.mark.asyncio
    async def test_api_key_cannot_manage_account_or_api_key_lifecycle(
        self, aclient, method, path, kwargs
    ):
        c, db, _ = aclient
        db.verify_api_key.return_value = _api_key_record("admin")

        r = await getattr(c, method)(path, headers=_api_key_headers(), **kwargs)

        assert r.status_code == 401

    @pytest.mark.asyncio
    async def test_cookie_logout_does_not_use_or_revoke_api_key(self, aclient):
        c, db, _ = aclient
        db.verify_api_key.reset_mock()
        db.revoke_refresh_cookie_session.reset_mock()
        c.cookies.delete("ares-dev-refresh")
        response = await c.post("/auth/logout", headers=_api_key_headers())
        _require_fixed(response.status_code == 204, "cookie logout was not idempotent")
        _require_fixed(db.verify_api_key.await_count == 0, "cookie logout verified API key")
        _require_fixed(
            db.revoke_refresh_cookie_session.await_count == 0,
            "cookie logout revoked family",
        )

    @pytest.mark.asyncio
    async def test_jwt_auth_can_create_list_and_delete_api_keys(self, aclient):
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        db.get_user.return_value = {"id": "user-1", "username": "admin"}
        db.create_api_key = AsyncMock(
            return_value=("api-key-1", "ares_created_secret_value")
        )
        db.list_api_keys = AsyncMock(
            return_value=[
                {
                    "id": "api-key-1",
                    "name": "ci",
                    "key_prefix": "ares_created",
                    "scopes": "read",
                }
            ]
        )
        db.revoke_api_key = AsyncMock(return_value=True)

        headers = _auth("admin", "team_lead")
        create = await c.post(
            "/auth/api-keys",
            headers=headers,
            json={"name": "ci", "scopes": "read"},
        )
        listed = await c.get("/auth/api-keys", headers=headers)
        deleted = await c.delete("/auth/api-keys/api-key-1", headers=headers)

        assert create.status_code == 200
        assert create.json()["key"] == "ares_created_secret_value"
        assert listed.status_code == 200
        item = listed.json()[0]
        assert item["key_prefix"] == "ares_created"
        assert "key" not in item
        assert "raw_key" not in item
        assert "key_hash" not in item
        assert deleted.status_code == 200
        assert deleted.json() == {"status": "revoked"}


class TestRBACEnforcement:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_register_requires_team_lead(self, aclient):
        """RBAC fires before body parse → 403 for reporter role."""
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        r = await c.post(
            "/auth/register",
            json={},
            headers=_auth("reporter_user", "reporter"),
        )
        assert r.status_code == 403

    @pytest.mark.asyncio
    async def test_security_audit_requires_team_lead(self, aclient):
        """GET /security/audit - operator role → 403."""
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        r = await c.get("/security/audit", headers=_auth("op_user", "operator"))
        assert r.status_code == 403

    @pytest.mark.asyncio
    async def test_security_audit_accessible_to_team_lead(self, aclient):
        """GET /security/audit - team_lead → 200."""
        c, db, _ = aclient
        _reset_rate_limiter()
        db.is_access_token_revoked.return_value = False
        r = await c.get("/security/audit", headers=_auth("lead", "team_lead"))
        assert r.status_code == 200

    @pytest.mark.asyncio
    async def test_campaigns_accessible_to_all_roles(self, aclient):
        """All authenticated roles can GET /campaigns."""
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        db.list_campaigns.return_value = ([], 0)
        for role in ("reporter", "recon", "operator", "team_lead"):
            _reset_rate_limiter()
            r = await c.get("/campaigns", headers=_auth(f"u_{role}", role))
            assert (
                r.status_code == 200
            ), f"Role {role!r} should access /campaigns, got {r.status_code}"

    @pytest.mark.asyncio
    async def test_create_campaign_invalid_scope_returns_422(self, aclient):
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        db.save_campaign.reset_mock()

        r = await c.post(
            "/campaigns",
            json={
                "name": "Invalid Scope",
                "client": "Internal",
                "targets": ["127.0.0.1"],
                "scope_cidrs": ["123"],
            },
            headers=_auth("op_user", "operator"),
        )

        assert r.status_code == 422
        assert "scope_cidrs" in r.text
        db.save_campaign.assert_not_called()

    @pytest.mark.asyncio
    async def test_create_campaign_normalizes_uppercase_noise_profile(self, aclient):
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        captured: dict[str, Any] = {}

        async def capture_campaign(campaign: Any) -> None:
            captured["campaign"] = campaign

        db.save_campaign.side_effect = capture_campaign

        try:
            r = await c.post(
                "/campaigns",
                json={
                    "name": "AD Lab Attack Simulation",
                    "client": "Internal",
                    "targets": ["10.10.10.20"],
                    "scope_cidrs": ["10.10.10.0/24"],
                    "noise_profile": "NORMAL",
                },
                headers=_auth("op_user", "operator"),
            )
        finally:
            db.save_campaign.side_effect = None

        assert r.status_code == 200
        assert r.json()["noise_profile"] == "normal"
        assert captured["campaign"].noise_profile.value == "normal"

    @pytest.mark.asyncio
    async def test_delete_campaign_requires_team_lead(self, aclient):
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-delete",
            "name": "Delete Me",
            "operator": "operator1",
        }
        db.delete_campaign.reset_mock()

        for role in ("reporter", "recon", "operator"):
            _reset_rate_limiter()
            r = await c.delete("/campaigns/camp-delete", headers=_auth(f"u_{role}", role))
            assert r.status_code == 403

        db.delete_campaign.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_delete_campaign_team_lead_deletes(self, aclient, tmp_path, monkeypatch):
        c, db, _ = aclient
        import ares.api.server as server

        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-delete",
            "name": "Delete Me",
            "operator": "operator1",
        }
        db.delete_campaign.return_value = True
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())
        owned_report = tmp_path / "camp-delete_Delete_Me_20260622_1745.pdf"
        owned_html_source = tmp_path / "camp-delete_Delete_Me_20260622_1745.html"
        other_report = tmp_path / "other-campaign_Delete_Me_20260622_1745.pdf"
        owned_report.write_text("owned pdf", encoding="utf-8")
        owned_html_source.write_text("owned html", encoding="utf-8")
        other_report.write_text("other pdf", encoding="utf-8")

        r = await c.delete("/campaigns/camp-delete", headers=_auth("admin", "team_lead"))

        assert r.status_code == 200
        assert r.json()["status"] == "deleted"
        db.delete_campaign.assert_awaited_once_with("camp-delete")
        assert not owned_report.exists()
        assert not owned_html_source.exists()
        assert other_report.exists()


# ── Pagination ────────────────────────────────────────────────────────────────


class TestPagination:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_x_total_count_header(self, aclient):
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        db.list_campaigns.return_value = ([], 42)
        r = await c.get("/campaigns", headers=_auth("admin", "team_lead"))
        assert r.status_code == 200
        assert r.headers.get("x-total-count") == "42"

    @pytest.mark.asyncio
    async def test_x_page_and_per_page_headers(self, aclient):
        c, db, _ = aclient
        _reset_rate_limiter()
        db.is_access_token_revoked.return_value = False
        db.list_campaigns.return_value = ([], 0)
        r = await c.get(
            "/campaigns?page=2&per_page=10", headers=_auth("admin", "team_lead")
        )
        assert r.status_code == 200
        assert r.headers.get("x-page") == "2"
        assert r.headers.get("x-per-page") == "10"


# ── Error handling ────────────────────────────────────────────────────────────


class TestFindingsEvidenceContainment:
    _MARKER = "SYNTHETIC-HTTP-EVIDENCE-MARKER"

    def setup_method(self):
        _reset_rate_limiter()

    @classmethod
    def _finding_row(cls) -> dict[str, Any]:
        return {
            "id": "finding-contained",
            "campaign_id": "camp-contained",
            "module_id": "demo.synthetic",
            "title": "Synthetic finding title",
            "description": "Synthetic finding description",
            "severity": "high",
            "confidence": 0.9,
            "evidence_json": (
                '{"nested":{"token":"' + cls._MARKER + '"},'
                '"keyless":"' + cls._MARKER + '"}'
            ),
            "remediation": "Synthetic remediation",
            "host": "host.example.test",
            "validated": 1,
            "false_positive": 0,
        }

    @staticmethod
    def _prepare_db(db: Any, *, operator: str) -> None:
        db.is_access_token_revoked.return_value = False
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = {
            "id": "camp-contained",
            "name": "Contained Findings",
            "operator": operator,
        }
        db.list_findings.side_effect = None
        db.list_findings.reset_mock()

    @pytest.mark.parametrize(
        "role", ("reporter", "recon", "operator", "team_lead")
    )
    @pytest.mark.asyncio
    async def test_default_findings_response_redacts_every_jwt_role(
        self, aclient, role
    ):
        c, db, _ = aclient
        username = f"user-{role}"
        self._prepare_db(db, operator=username)
        row = self._finding_row()
        db.list_findings.return_value = ([row], 1)

        response = await c.get(
            "/campaigns/camp-contained/findings",
            headers=_auth(username, role),
        )

        assert response.status_code == 200
        assert response.json()[0]["evidence_json"] == '{"redacted":true}'
        assert response.json()[0]["title"] == row["title"]
        assert response.json()[0]["description"] == row["description"]
        assert self._MARKER not in response.text

    @pytest.mark.asyncio
    async def test_read_scoped_api_key_receives_redacted_findings(self, aclient):
        c, db, _ = aclient
        self._prepare_db(db, operator="api-reader")
        row = self._finding_row()
        db.list_findings.return_value = ([row], 1)
        db.verify_api_key.return_value = _api_key_record(
            "read",
            username="api-reader",
            role="reporter",
        )

        try:
            response = await c.get(
                "/campaigns/camp-contained/findings",
                headers=_api_key_headers(),
            )
        finally:
            db.verify_api_key.return_value = None

        assert response.status_code == 200
        assert response.json()[0]["evidence_json"] == '{"redacted":true}'
        assert self._MARKER not in response.text

    @pytest.mark.asyncio
    async def test_findings_preserve_filters_headers_total_and_db_rows(self, aclient):
        c, db, _ = aclient
        self._prepare_db(db, operator="operator-user")
        row = self._finding_row()
        original = dict(row)
        db.list_findings.return_value = ([row], 37)

        response = await c.get(
            "/campaigns/camp-contained/findings"
            "?page=2&per_page=7&severity=high&false_positive=true",
            headers=_auth("operator-user", "operator"),
        )

        assert response.status_code == 200
        assert response.headers["x-total-count"] == "37"
        assert response.headers["x-page"] == "2"
        assert response.headers["x-per-page"] == "7"
        db.list_findings.assert_awaited_once_with(
            "camp-contained", 2, 7, "high", True
        )
        assert row == original
        assert response.json()[0]["evidence_json"] == '{"redacted":true}'
        assert self._MARKER not in response.text

    @pytest.mark.asyncio
    async def test_campaign_ownership_denial_remains_404(self, aclient):
        c, db, _ = aclient
        self._prepare_db(db, operator="campaign-owner")

        response = await c.get(
            "/campaigns/camp-contained/findings",
            headers=_auth("different-reporter", "reporter"),
        )

        assert response.status_code == 404
        db.list_findings.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_unknown_raw_query_flags_cannot_bypass_redaction(self, aclient):
        c, db, _ = aclient
        self._prepare_db(db, operator="admin")
        row = self._finding_row()
        db.list_findings.return_value = ([row], 1)

        response = await c.get(
            "/campaigns/camp-contained/findings?raw=true&include_sensitive=true",
            headers=_auth("admin", "team_lead"),
        )

        assert response.status_code == 200
        assert response.json()[0]["evidence_json"] == '{"redacted":true}'
        assert self._MARKER not in response.text


class TestErrorHandling:
    def setup_method(self):
        _reset_rate_limiter()

    @pytest.mark.asyncio
    async def test_unknown_route_returns_404(self, aclient):
        c, _, __ = aclient
        assert (await c.get("/this-route-does-not-exist-xyz")).status_code == 404

    @pytest.mark.asyncio
    async def test_campaign_not_found_returns_404(self, aclient):
        c, db, _ = aclient
        _reset_rate_limiter()
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = None
        r = await c.get(
            "/campaigns/nonexistent-id-xyz", headers=_auth("admin", "team_lead")
        )
        assert r.status_code == 404


# ── Route inventory and dashboard static serving ─────────────────────────────


class TestRouteInventoryAndDashboard:
    def setup_method(self) -> None:
        _reset_rate_limiter()

    def test_required_routes_registered(self, aclient: Any) -> None:
        _, __, app = aclient
        inventory = {
            (method, getattr(route, "path", ""))
            for route in app.routes
            for method in (getattr(route, "methods", None) or {"WS"})
        }
        required = {
            ("POST", "/auth/token"),
            ("POST", "/auth/refresh"),
            ("POST", "/auth/logout"),
            ("GET", "/auth/me"),
            ("POST", "/campaigns"),
            ("GET", "/campaigns"),
            ("DELETE", "/campaigns/{campaign_id}"),
            ("GET", "/modules"),
            ("GET", "/modules/execution-chains"),
            ("POST", "/modules/{module_id}/run"),
            ("POST", "/reports/{campaign_id}"),
            ("GET", "/reports/{campaign_id}"),
            ("GET", "/reports/{campaign_id}/files/{filename}"),
            ("GET", "/health"),
            ("WS", "/ws/campaigns/{campaign_id}/events"),
            ("WS", "/dashboard"),
        }
        missing = required - inventory
        assert not missing

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_dashboard_index_and_spa_fallback(
        self, aclient: Any, tmp_path: Any
    ) -> None:
        c, _, app = aclient
        dist = tmp_path / "dist"
        dist.mkdir()
        (dist / "index.html").write_text(
            '<div id="root">ARES Dashboard</div>', encoding="utf-8"
        )
        (dist / "assets").mkdir()
        (dist / "assets" / "app.js").write_text("console.log('ok')", encoding="utf-8")
        for route in app.routes:
            if getattr(route, "name", "") == "dashboard":
                route.app.directory = str(dist)
                route.app.all_directories = [str(dist)]
                route.app.config_checked = False
                break
        r = await c.get("/dashboard/")
        assert r.status_code == 200
        assert "ARES Dashboard" in r.text
        fallback = await c.get("/dashboard/campaigns/demo")
        assert fallback.status_code == 200
        assert "ARES Dashboard" in fallback.text


# ── Modules schema metadata ──────────────────────────────────────────────────


class TestModuleSchemaEndpoint:
    def setup_method(self) -> None:
        _reset_rate_limiter()

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_modules_include_param_schema_from_backend(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine
        from ares.modules.base import OpsecLevel

        class FakeModule:
            MODULE_CATEGORY = "ad"
            MODULE_DESCRIPTION = "Kerberoast test module"
            OPSEC_LEVEL = OpsecLevel.MEDIUM
            MITRE_TECHNIQUES = ["T1558.003"]

        class FakeRegistry:
            def get(self, module_id: str) -> Any:
                return FakeModule if module_id == "ad.kerberoast" else None

        class FakeEngine:
            registry = FakeRegistry()

            def list_modules(self) -> list[dict[str, str]]:
                return [{"id": "ad.kerberoast", "name": "Kerberoast"}]

        db.is_access_token_revoked.return_value = False
        app.dependency_overrides[get_engine] = lambda: FakeEngine()
        try:
            r = await c.get("/modules", headers=_auth("admin", "team_lead"))
        finally:
            app.dependency_overrides.pop(get_engine, None)
        assert r.status_code == 200
        module = r.json()[0]
        assert module["category"] == "ad"
        assert module["opsec_level"] == "medium"
        assert module["mitre_list"] == ["T1558.003"]
        assert "dc" in module["param_schema"]
        assert module["param_schema"]["password"]["secret"] is True
        for field in (
            "required_params",
            "optional_params",
            "defaults",
            "capability_flags",
            "dry_run_supported",
            "supported_modes",
            "dependency_notes",
            "outcome_semantics",
            "safe_error_categories",
        ):
            assert field in module
        assert module["dry_run_supported"] is True

    @pytest.mark.asyncio
    async def test_disabled_ghost_forge_module_rejected_via_api(
        self, aclient: Any
    ) -> None:
        from ares.api.server import app, get_engine
        from ares.core.campaign import Campaign, ScopeEntry
        from ares.core.engine import AresEngine
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        campaign = Campaign(name="Disabled Test", client="Client", scope=[ScopeEntry(cidr="10.0.0.0/24")])
        db.get_campaign.return_value = campaign

        real_engine = AresEngine()
        real_engine.load_modules()
        app.dependency_overrides[get_engine] = lambda: real_engine
        try:
            # 1. Verify ad.ghost_forge does NOT appear in GET /modules
            res = await c.get("/modules", headers=_auth("admin", "team_lead"))
            assert res.status_code == 200
            module_ids = [m["id"] for m in res.json()]
            assert "ad.ghost_forge" not in module_ids

            # 2. Verify POST /modules/ad.ghost_forge/run is rejected with explicit 400 error
            res_run = await c.post(
                "/modules/ad.ghost_forge/run",
                json={
                    "campaign_id": campaign.id,
                    "target": "10.0.0.1",
                    "params": {"dc": "10.0.0.1", "username": "admin", "password": "Password123!"},
                },
                headers={
                    **_auth("admin", "team_lead"),
                    "X-Idempotency-Key": "00000000-0000-4000-8000-000000000001",
                },
            )
            assert res_run.status_code == 400
            assert "module disabled: implementation incomplete, see MOD-005" in res_run.json()["detail"]
        finally:
            app.dependency_overrides.pop(get_engine, None)

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_execution_chains_are_available_with_module_metadata(
        self, aclient: Any
    ) -> None:
        c, db, _ = aclient
        db.is_access_token_revoked.return_value = False
        response = await c.get("/modules/execution-chains", headers=_auth("admin", "team_lead"))

        assert response.status_code == 200
        chains = response.json()
        assert len(chains) >= 7
        kerberos = next(chain for chain in chains if chain["id"] == "ad-kerberos-exposure-chain")
        assert kerberos["stages"][1]["module_ids"] == ["ad.enum_spn"]
        assert kerberos["stages"][2]["module_ids"] == ["ad.kerberoast"]


# ── Reports safety ───────────────────────────────────────────────────────────


class TestHighNoiseAuthorizationPolicy:
    _INVALID_PLAN_DETAIL = (
        "Invalid plan: every stage must contain a modules list of non-empty "
        "string module IDs."
    )

    def setup_method(self) -> None:
        _reset_rate_limiter()

    @staticmethod
    def _module_classes() -> tuple[type, type]:
        from ares.modules.base import OpsecLevel

        class SafeModule:
            OPSEC_LEVEL = OpsecLevel.LOW

        class HighNoiseModule:
            OPSEC_LEVEL = OpsecLevel.HIGH_NOISE

        return SafeModule, HighNoiseModule

    @staticmethod
    def _actor(role: str, username: str = "operator-user") -> Any:
        from ares.api.rbac import AuthenticatedUser

        return AuthenticatedUser(username=username, role=role)

    @classmethod
    def _engine(cls, registry_items: dict[str, type | None]) -> Any:
        registry = MagicMock()
        registry.get.side_effect = registry_items.get

        def result_for(module_id: str) -> Any:
            result = SimpleNamespace(
                status="done",
                findings=[],
                error="",
                duration_ms=1.0,
            )
            result.model_dump = lambda: {
                "module_id": module_id,
                "status": "done",
                "findings": [],
                "validation_results": [],
                "raw_output": {},
                "error": "",
                "duration_ms": 1.0,
            }
            return result

        async def run_module(
            module_id: str,
            campaign: Any,
            params: dict[str, Any],
            actor_role: str = "",
        ) -> Any:
            return result_for(module_id)

        async def run_plan(
            plan: Any,
            campaign: Any,
            global_params: dict[str, Any],
            actor_role: str = "",
        ) -> dict[str, Any]:
            return {
                module_id: result_for(module_id)
                for module_id in plan.all_module_ids()
            }

        engine = SimpleNamespace(registry=registry)
        engine.run_module = AsyncMock(side_effect=run_module)
        engine.run_plan = AsyncMock(side_effect=run_plan)
        engine.dry_run_plan = MagicMock(
            return_value={
                "status": "dry_run_ok",
                "modules": [],
                "would_execute": True,
            }
        )
        return engine

    @staticmethod
    def _campaign(operator: str = "operator-user") -> dict[str, Any]:
        return {
            "id": "camp-plan-policy",
            "name": "Plan Policy",
            "client": "Internal",
            "operator": operator,
            "noise_profile": "normal",
            "status": "created",
            "scope_json": "[]",
            "targets_json": "[]",
            "notes": "",
        }

    @staticmethod
    def _plan_body(
        stages: list[tuple[str, list[str]]],
        *,
        dry_run: bool = False,
        global_params: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        return {
            "plan": {
                "stages": [
                    {"name": name, "modules": modules, "params": {}}
                    for name, modules in stages
                ]
            },
            "global_params": global_params or {},
            "dry_run": dry_run,
        }

    def test_shared_policy_allows_operator_for_normal_module(self) -> None:
        from ares.api.server import _require_high_noise_module_access

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})

        _require_high_noise_module_access(
            ["plugin.safe"], self._actor("operator"), engine
        )

        engine.registry.get.assert_called_once_with("plugin.safe")

    def test_shared_policy_blocks_dynamic_high_noise_module(self) -> None:
        from ares.api.server import _require_high_noise_module_access

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})

        with pytest.raises(HTTPException) as exc_info:
            _require_high_noise_module_access(
                ["plugin.dynamic-high"], self._actor("operator"), engine
            )

        assert exc_info.value.status_code == 403
        assert exc_info.value.detail == (
            "'plugin.dynamic-high' is HIGH_NOISE - team_lead only."
        )

    def test_shared_policy_allows_team_lead_for_high_noise_module(self) -> None:
        from ares.api.server import _require_high_noise_module_access

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})

        _require_high_noise_module_access(
            ["plugin.dynamic-high"], self._actor("team_lead"), engine
        )

    def test_shared_policy_delegates_unknown_module(self) -> None:
        from ares.api.server import _require_high_noise_module_access

        engine = self._engine({})

        _require_high_noise_module_access(
            ["plugin.unknown"], self._actor("operator"), engine
        )

        engine.registry.get.assert_called_once_with("plugin.unknown")

    def test_shared_policy_deduplicates_sorts_and_excludes_sensitive_values(
        self,
    ) -> None:
        from ares.api.server import _require_high_noise_module_access

        _, high_noise_module = self._module_classes()
        engine = self._engine(
            {
                "plugin.zeta-high": high_noise_module,
                "plugin.alpha-high": high_noise_module,
            }
        )

        with pytest.raises(HTTPException) as exc_info:
            _require_high_noise_module_access(
                [
                    "plugin.zeta-high",
                    "plugin.alpha-high",
                    "plugin.zeta-high",
                ],
                self._actor("operator"),
                engine,
            )

        detail = str(exc_info.value.detail)
        assert detail == (
            "'plugin.alpha-high', 'plugin.zeta-high' "
            "are HIGH_NOISE - team_lead only."
        )
        assert [call.args[0] for call in engine.registry.get.call_args_list] == [
            "plugin.alpha-high",
            "plugin.zeta-high",
        ]
        for sensitive_marker in (
            "plan-param-marker",
            "target-marker",
            "credential-marker",
            "evidence-marker",
        ):
            assert sensitive_marker not in detail

    @pytest.mark.parametrize(
        "module_ids",
        [
            pytest.param(["plugin.safe", 7], id="mixed-string-integer"),
            pytest.param([None], id="null"),
            pytest.param([["plugin.safe"]], id="list"),
            pytest.param([{"module_id": "plugin.safe"}], id="dict"),
            pytest.param([("plugin.safe",)], id="tuple"),
            pytest.param([b"plugin.safe"], id="bytes"),
            pytest.param([""], id="empty-string"),
            pytest.param(["   "], id="whitespace-only"),
            pytest.param([True], id="bool"),
        ],
    )
    def test_shared_policy_rejects_invalid_ids_before_registry_lookup(
        self, module_ids: list[Any]
    ) -> None:
        from ares.api.server import _require_high_noise_module_access

        engine = self._engine({})

        with pytest.raises(HTTPException) as exc_info:
            _require_high_noise_module_access(
                module_ids,
                self._actor("operator"),
                engine,
            )

        assert exc_info.value.status_code == 422
        assert exc_info.value.detail == self._INVALID_PLAN_DETAIL
        engine.registry.get.assert_not_called()

    @pytest.mark.parametrize(
        "plan_data",
        [
            pytest.param({"stages": [None]}, id="non-mapping-stage"),
            pytest.param({"stages": [{}]}, id="missing-modules"),
            pytest.param(
                {"stages": [{"modules": None}]},
                id="invalid-modules-collection",
            ),
            pytest.param(
                {"stages": [{"modules": [[]]}]},
                id="unhashable-module-id",
            ),
        ],
    )
    def test_plan_module_id_collector_rejects_structure_with_canonical_422(
        self, plan_data: dict[str, Any]
    ) -> None:
        from ares.api.server import _collect_plan_module_ids_for_authorization

        with pytest.raises(HTTPException) as exc_info:
            _collect_plan_module_ids_for_authorization(plan_data)

        assert exc_info.value.status_code == 422
        assert exc_info.value.detail == self._INVALID_PLAN_DETAIL

    def test_plan_module_id_collector_preserves_absent_stages_and_valid_ids(
        self,
    ) -> None:
        from ares.api.server import _collect_plan_module_ids_for_authorization

        assert _collect_plan_module_ids_for_authorization({}) == []
        module_ids = _collect_plan_module_ids_for_authorization(
            {
                "stages": [
                    {
                        "modules": [
                            " plugin.safe ",
                            "plugin.safe",
                            " plugin.safe ",
                        ]
                    }
                ]
            }
        )

        assert module_ids == [" plugin.safe ", "plugin.safe"]

    @pytest.mark.asyncio
    async def test_single_module_operator_high_noise_denied_before_engine(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_c_live_runtime, get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        runtime = MagicMock()
        original_runtime = app.dependency_overrides[get_c_live_runtime]
        db.get_campaign.reset_mock()
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = None
        app.dependency_overrides[get_engine] = lambda: engine
        app.dependency_overrides[get_c_live_runtime] = lambda: runtime
        try:
            with patch(
                "ares.api.server._broadcast_event",
                new_callable=AsyncMock,
            ) as broadcast:
                response = await c.post(
                    "/modules/plugin.dynamic-high/run",
                    json={
                        "campaign_id": "camp-plan-policy",
                        "params": {"target": "target-marker"},
                        "dry_run": False,
                    },
                    headers=_auth("operator-user", "operator"),
                )
        finally:
            app.dependency_overrides.pop(get_engine, None)
            app.dependency_overrides[get_c_live_runtime] = original_runtime

        # Live authority starts with the durable campaign identity; legacy
        # module classes are not an execution-authority source.
        assert response.status_code == 404
        assert response.json()["detail"] == "Campaign not found"
        db.get_campaign.assert_awaited_once_with("camp-plan-policy")
        engine.registry.get.assert_not_called()
        runtime.bind.assert_not_called()
        engine.run_module.assert_not_awaited()
        broadcast.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_single_module_team_lead_high_noise_reaches_engine(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign("another-operator")
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/modules/plugin.dynamic-high/run",
                json={
                    "campaign_id": "camp-plan-policy",
                    "params": {},
                    "dry_run": False,
                },
                headers=_auth("lead-user", "team_lead"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        engine.run_module.assert_awaited_once()

    @pytest.mark.asyncio
    async def test_single_module_normal_and_unknown_modules_reach_existing_path(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            safe_response = await c.post(
                "/modules/plugin.safe/run",
                json={
                    "campaign_id": "camp-plan-policy",
                    "params": {},
                    "dry_run": False,
                },
                headers=_auth("operator-user", "operator"),
            )
            unknown_response = await c.post(
                "/modules/plugin.unknown/run",
                json={
                    "campaign_id": "camp-plan-policy",
                    "params": {},
                    "dry_run": False,
                },
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert safe_response.status_code == 200
        assert unknown_response.status_code == 200
        assert [call.args[0] for call in engine.run_module.await_args_list] == [
            "plugin.safe",
            "plugin.unknown",
        ]

    @pytest.mark.asyncio
    async def test_operator_safe_live_plan_reaches_engine_with_stable_response(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body([("safe", ["plugin.safe"])]),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        payload = response.json()
        assert payload["campaign_id"] == "camp-plan-policy"
        assert payload["modules_run"] == 1
        assert [child["module_id"] for child in payload["children"]] == [
            "plugin.safe"
        ]
        assert payload["children"][0]["status"] == "done"
        assert payload["children"][0]["execution"]["attempt_id"]
        engine.run_module.assert_awaited_once()
        assert engine.run_module.await_args.kwargs["actor_role"] == "operator"
        engine.run_plan.assert_not_awaited()

    @pytest.mark.parametrize(
        "stages",
        [
            [
                ("forbidden", ["plugin.dynamic-high"]),
                ("safe", ["plugin.safe"]),
            ],
            [
                ("safe", ["plugin.safe"]),
                ("forbidden", ["plugin.dynamic-high"]),
            ],
        ],
        ids=("high-noise-first", "high-noise-later"),
    )
    @pytest.mark.asyncio
    async def test_operator_high_noise_live_plan_denied_before_any_execution(
        self,
        aclient: Any,
        stages: list[tuple[str, list[str]]],
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, high_noise_module = self._module_classes()
        engine = self._engine(
            {
                "plugin.safe": safe_module,
                "plugin.dynamic-high": high_noise_module,
            }
        )
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(stages),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        expected_modules = [module_id for _name, module_ids in stages for module_id in module_ids]
        assert [
            call.args[0] for call in engine.run_module.await_args_list
        ] == expected_modules
        # The legacy HIGH_NOISE class is not an authority source. Descriptor
        # minimum-role metadata is the sole live role gate.
        engine.run_plan.assert_not_awaited()
        engine.dry_run_plan.assert_not_called()

    @pytest.mark.asyncio
    async def test_team_lead_high_noise_live_plan_reaches_engine(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign("another-operator")
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(
                    [("forbidden", ["plugin.dynamic-high"])]
                ),
                headers=_auth("lead-user", "team_lead"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        engine.run_module.assert_awaited_once()
        assert engine.run_module.await_args.kwargs["actor_role"] == "team_lead"
        engine.run_plan.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_duplicate_high_noise_plan_detail_is_safe_and_deterministic(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine(
            {
                "plugin.zeta-high": high_noise_module,
                "plugin.alpha-high": high_noise_module,
            }
        )
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        body = self._plan_body(
            [
                (
                    "mixed",
                    [
                        "plugin.zeta-high",
                        "plugin.alpha-high",
                        "plugin.zeta-high",
                    ],
                )
            ],
            global_params={
                "target": "target-marker",
                "credential": "credential-marker",
                "evidence": "evidence-marker",
            },
        )
        body["plan"]["stages"][0]["params"] = {
            "plugin.zeta-high": {"command": "plan-param-marker"}
        }
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=body,
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 422
        assert response.json()["detail"] == "raw_secret_material_forbidden"
        for sensitive_marker in (
            "plan-param-marker",
            "target-marker",
            "credential-marker",
            "evidence-marker",
        ):
            assert sensitive_marker not in response.text
        engine.run_module.assert_not_awaited()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.parametrize(
        "modules",
        [
            pytest.param(["plugin.safe", 7], id="mixed-string-integer"),
            pytest.param([None], id="null-entry"),
            pytest.param([["plugin.safe"]], id="list-entry"),
            pytest.param([{"module_id": "plugin.safe"}], id="dict-entry"),
            pytest.param(None, id="null-collection"),
            pytest.param(7, id="integer-collection"),
            pytest.param("plugin.safe", id="string-collection"),
            pytest.param(
                {"module_id": "plugin.safe"},
                id="dict-collection",
            ),
            pytest.param([""], id="empty-string"),
            pytest.param(["   "], id="whitespace-only"),
            pytest.param([True], id="bool-entry"),
        ],
    )
    @pytest.mark.parametrize(
        "dry_run",
        [False, True],
        ids=("live", "dry-run"),
    )
    @pytest.mark.asyncio
    async def test_malformed_plan_module_ids_return_stable_422_before_policy_lookup(
        self,
        aclient: Any,
        modules: Any,
        dry_run: bool,
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json={
                    "plan": {
                        "stages": [
                            {
                                "name": "malformed",
                                "modules": modules,
                                "params": {},
                            }
                        ]
                    },
                    "dry_run": dry_run,
                },
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 422
        assert response.json() == {
            "code": 422,
            "detail": self._INVALID_PLAN_DETAIL,
            "type": "api_error",
        }
        engine.registry.get.assert_not_called()
        engine.run_plan.assert_not_awaited()
        engine.dry_run_plan.assert_not_called()

    @pytest.mark.parametrize(
        "plan_data",
        [
            pytest.param({"stages": [None]}, id="null-stage"),
            pytest.param({"stages": [123]}, id="integer-stage"),
            pytest.param({"stages": ["invalid"]}, id="string-stage"),
            pytest.param({"stages": [[]]}, id="list-stage"),
            pytest.param({"stages": [{}]}, id="missing-modules"),
            pytest.param(
                {
                    "stages": [
                        {
                            "name": "safe",
                            "modules": ["plugin.safe"],
                            "params": {},
                        },
                        None,
                    ]
                },
                id="malformed-later-stage",
            ),
            pytest.param(
                {"stages": "invalid-stages-collection"},
                id="invalid-stages-collection",
            ),
        ],
    )
    @pytest.mark.parametrize(
        "dry_run",
        [False, True],
        ids=("live", "dry-run"),
    )
    @pytest.mark.asyncio
    async def test_malformed_plan_structure_returns_canonical_422_before_engine(
        self,
        aclient: Any,
        plan_data: dict[str, Any],
        dry_run: bool,
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json={"plan": plan_data, "dry_run": dry_run},
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 422
        assert response.json() == {
            "code": 422,
            "detail": self._INVALID_PLAN_DETAIL,
            "type": "api_error",
        }
        assert str(plan_data) not in response.text
        engine.registry.get.assert_not_called()
        engine.run_plan.assert_not_awaited()
        engine.dry_run_plan.assert_not_called()

    @pytest.mark.asyncio
    async def test_unknown_valid_plan_module_is_delegated_to_engine(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        engine = self._engine({})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(
                    [("unknown", ["plugin.unknown"])]
                ),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        engine.registry.get.assert_not_called()
        engine.run_module.assert_awaited_once()
        assert engine.run_module.await_args.args[0] == "plugin.unknown"
        engine.run_plan.assert_not_awaited()
        engine.dry_run_plan.assert_not_called()

    @pytest.mark.asyncio
    async def test_operator_safe_dry_run_reaches_preview_only(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(
                    [("safe", ["plugin.safe"])], dry_run=True
                ),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        assert response.json()["status"] == "dry_run_ok"
        engine.dry_run_plan.assert_called_once()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_operator_high_noise_dry_run_denied_before_preview(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(
                    [("forbidden", ["plugin.dynamic-high"])],
                    dry_run=True,
                ),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        assert response.json()["status"] == "dry_run_ok"
        engine.dry_run_plan.assert_called_once()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_team_lead_high_noise_dry_run_reaches_preview(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign("another-operator")
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(
                    [("forbidden", ["plugin.dynamic-high"])],
                    dry_run=True,
                ),
                headers=_auth("lead-user", "team_lead"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        engine.dry_run_plan.assert_called_once()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_plan_missing_campaign_precedes_policy_lookup(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = None
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/missing/run",
                json=self._plan_body(
                    [("forbidden", ["plugin.dynamic-high"])]
                ),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 404
        engine.registry.get.assert_not_called()
        engine.run_module.assert_not_awaited()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_plan_campaign_ownership_denial_precedes_policy_lookup(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        _, high_noise_module = self._module_classes()
        engine = self._engine({"plugin.dynamic-high": high_noise_module})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign("different-owner")
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body(
                    [("forbidden", ["plugin.dynamic-high"])]
                ),
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        # The legacy campaign.operator username is not canonical execution
        # authority. The durable campaign grant is enforced by admission.
        assert response.status_code == 200
        assert response.json()["modules_run"] == 1
        engine.registry.get.assert_not_called()
        engine.run_module.assert_awaited_once()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.asyncio
    async def test_invalid_plan_structure_remains_422_before_policy_lookup(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        engine = self._engine({})
        db.get_campaign.side_effect = None
        db.get_campaign.return_value = self._campaign()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json={"plan": {"stages": [{}]}, "dry_run": False},
                headers=_auth("operator-user", "operator"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 422
        engine.registry.get.assert_not_called()
        engine.run_plan.assert_not_awaited()

    @pytest.mark.parametrize("role", ("reporter", "recon"))
    @pytest.mark.asyncio
    async def test_plan_reporter_and_recon_access_remains_forbidden(
        self, aclient: Any, role: str
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        safe_module, _ = self._module_classes()
        engine = self._engine({"plugin.safe": safe_module})
        db.get_campaign.reset_mock()
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            response = await c.post(
                "/campaigns/camp-plan-policy/run",
                json=self._plan_body([("safe", ["plugin.safe"])]),
                headers=_auth(f"{role}-user", role),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 403
        db.get_campaign.assert_not_awaited()
        engine.run_plan.assert_not_awaited()


@pytest.mark.parametrize(
    "case",
    [
        "missing-bearer",
        "invalid-bearer",
        "revoked-bearer",
        "deleted-user",
        "inactive-user",
        "demoted-role",
        "exact-replay-no-engine",
        "conflict-no-engine",
    ],
)
@pytest.mark.asyncio
async def test_c_live_http_authentication_and_submission_lookup(
    case: str,
    c_live_route: Any,
) -> None:
    from ares.core.execution_admission import DispatchDispositionV1
    from ares.db.execution_lifecycle import FixedResult

    client, db, _app, engine, install = c_live_route
    db.get_campaign.reset_mock()
    coordinator = _RecordingLiveCoordinator()
    username = f"c-live-{case}"
    headers = _auth(username, "operator")
    expected_status = 401
    if case == "missing-bearer":
        headers = {"Idempotency-Key": _C_LIVE_TEST_KEY}
    elif case == "invalid-bearer":
        headers = {
            "Authorization": "Bearer invalid.c-live.token",
            "Idempotency-Key": _C_LIVE_TEST_KEY,
        }
    elif case == "revoked-bearer":
        db.is_access_token_revoked.return_value = True
    elif case in {"deleted-user", "inactive-user"}:
        db.resolve_access_token_principal.side_effect = None
        db.resolve_access_token_principal.return_value = None
    elif case == "demoted-role":
        headers = _auth(username, "reporter")
        expected_status = 403
    elif case == "exact-replay-no-engine":
        coordinator = _RecordingLiveCoordinator(
            lambda _request: _nonterminal_outcome(
                FixedResult.REPLAYED,
                DispatchDispositionV1.REPLAYED,
            )
        )
        expected_status = 409
    else:
        coordinator = _RecordingLiveCoordinator(
            lambda _request: _nonterminal_outcome(
                FixedResult.CONFLICT_OPERATION,
                DispatchDispositionV1.CONFLICT,
            )
        )
        expected_status = 409
    install(coordinator)

    response = await client.post(
        "/modules/plugin.safe/run",
        json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
        headers=headers,
    )

    assert response.status_code == expected_status
    engine.run_module.assert_not_awaited()
    if case in {"exact-replay-no-engine", "conflict-no-engine"}:
        assert len(coordinator.requests) == 1
        assert len(coordinator.principals) == 1
        assert coordinator.principals[0].subject_ref == coordinator.principals[0].user_id
        assert coordinator.principals[0].user_id == f"mock-user-{username}"
        assert coordinator.principals[0].subject_ref != username
        assert db.get_campaign.await_count == 1
    else:
        assert not coordinator.requests
        db.get_campaign.assert_not_awaited()


@pytest.mark.parametrize("route", ["module", "plan", "strategy"])
@pytest.mark.asyncio
async def test_c_live_authenticated_dispatch_uses_v3_admission(
    route: str,
    c_live_route: Any,
    monkeypatch: Any,
) -> None:
    import ares.api.server as server

    client, _db, _app, engine, install = c_live_route
    coordinator = _RecordingLiveCoordinator()
    install(coordinator)
    headers = _auth(f"c-live-{route}", "operator")
    if route == "module":
        response = await client.post(
            "/modules/plugin.safe/run",
            json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
            headers=headers,
        )
        expected_ingress = "api_module"
    elif route == "plan":
        response = await client.post(
            "/campaigns/camp-c-live/run",
            json={
                "plan": {"stages": [{"name": "one", "modules": ["plugin.safe"]}]},
                "global_params": {},
                "dry_run": False,
            },
            headers=headers,
        )
        expected_ingress = "api_campaign_plan"
    else:
        monkeypatch.setattr(
            server,
            "_strategy_test_plan",
            lambda _body: {"stages": [{"name": "one", "modules": ["plugin.safe"]}]},
        )
        response = await client.post(
            "/strategy/engage",
            json={"campaign_id": "camp-c-live"},
            headers=headers,
        )
        expected_ingress = "strategy"

    assert response.status_code == 200
    assert [item.ingress_code for item in coordinator.requests] == [expected_ingress]
    engine.run_module.assert_not_awaited()


@pytest.mark.parametrize("route", ["module", "plan", "strategy"])
@pytest.mark.asyncio
async def test_c_live_admission_denial_prevents_engine(
    route: str,
    c_live_route: Any,
    monkeypatch: Any,
) -> None:
    import ares.api.server as server
    from ares.core.execution_admission import DispatchDispositionV1
    from ares.db.execution_lifecycle import FixedResult

    client, _db, _app, engine, install = c_live_route
    coordinator = _RecordingLiveCoordinator(
        lambda _request: _nonterminal_outcome(
            FixedResult.AUTHORITY_STALE,
            DispatchDispositionV1.NON_DISPATCHABLE,
        )
    )
    install(coordinator)
    headers = _auth(f"c-live-denied-{route}", "operator")
    if route == "module":
        response = await client.post(
            "/modules/plugin.safe/run",
            json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
            headers=headers,
        )
    elif route == "plan":
        response = await client.post(
            "/campaigns/camp-c-live/run",
            json={
                "plan": {"stages": [{"name": "one", "modules": ["plugin.safe"]}]},
                "global_params": {},
                "dry_run": False,
            },
            headers=headers,
        )
    else:
        monkeypatch.setattr(
            server,
            "_strategy_test_plan",
            lambda _body: {"stages": [{"name": "one", "modules": ["plugin.safe"]}]},
        )
        response = await client.post(
            "/strategy/engage",
            json={"campaign_id": "camp-c-live"},
            headers=headers,
        )

    assert response.status_code == 409
    assert response.json()["type"] == "execution_authority_stale"
    engine.run_module.assert_not_awaited()


@pytest.mark.parametrize("case", ["missing", "invalid"])
@pytest.mark.asyncio
async def test_c_live_idempotency_key_validation(case: str, c_live_route: Any) -> None:
    client, db, _app, engine, _install = c_live_route
    headers = {
        "Authorization": f"Bearer {_make_token(f'key-{case}', 'operator')}"
    }
    if case == "invalid":
        headers["Idempotency-Key"] = "11111111-1111-1111-8111-111111111111"
    db.get_campaign.reset_mock()

    response = await client.post(
        "/modules/plugin.safe/run",
        json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
        headers=headers,
    )

    assert response.status_code == 422
    assert response.json()["detail"] == (
        "idempotency_key_required" if case == "missing" else "idempotency_key_invalid"
    )
    assert db.get_campaign.await_count == 1
    engine.run_module.assert_not_awaited()


@pytest.mark.asyncio
async def test_c_live_api_key_execution_is_denied(c_live_route: Any) -> None:
    client, db, _app, engine, _install = c_live_route
    db.verify_api_key.reset_mock()
    response = await client.post(
        "/modules/plugin.safe/run",
        json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
        headers={"X-API-Key": "opaque-api-key", "Idempotency-Key": _C_LIVE_TEST_KEY},
    )

    assert response.status_code == 403
    assert response.json()["detail"] == "api_key_execution_denied"
    db.verify_api_key.assert_not_awaited()
    engine.run_module.assert_not_awaited()


@pytest.mark.asyncio
async def test_c_live_raw_credential_material_is_rejected(c_live_route: Any) -> None:
    client, _db, _app, engine, _install = c_live_route
    response = await client.post(
        "/modules/plugin.safe/run",
        json={
            "campaign_id": "camp-c-live",
            "params": {"password": "must-never-cross-live-boundary"},
            "dry_run": False,
        },
        headers=_auth("raw-secret-user", "operator"),
    )

    assert response.status_code == 422
    assert response.json()["detail"] == "raw_secret_material_forbidden"
    engine.run_module.assert_not_awaited()


@pytest.mark.parametrize("route", ["module", "plan"])
@pytest.mark.asyncio
async def test_c_live_http_preview_executes_no_module_code(
    route: str,
    c_live_route: Any,
) -> None:
    client, _db, _app, engine, _install = c_live_route
    headers = {"Authorization": f"Bearer {_make_token(f'preview-{route}', 'operator')}"}
    if route == "module":
        response = await client.post(
            "/modules/plugin.safe/run",
            json={"campaign_id": "camp-c-live", "params": {}, "dry_run": True},
            headers=headers,
        )
        engine.dry_run_module.assert_called_once()
    else:
        response = await client.post(
            "/campaigns/camp-c-live/run",
            json={
                "plan": {"stages": [{"name": "one", "modules": ["plugin.safe"]}]},
                "global_params": {},
                "dry_run": True,
            },
            headers=headers,
        )
        engine.dry_run_plan.assert_called_once()
    assert response.status_code == 200
    engine.run_module.assert_not_awaited()


@pytest.mark.parametrize("authority", ["credential", "approval"])
def test_c_live_required_authority_module_is_non_dispatchable(authority: str) -> None:
    from ares.modules.descriptors import FIRST_PARTY_DESCRIPTORS, ContractState

    assert _PRODUCTION_C_LIVE_DESCRIPTOR_GATE is not None
    if authority == "approval":
        descriptors = [
            item for item in FIRST_PARTY_DESCRIPTORS.values() if item.explicit_attempt_approval
        ]
    else:
        descriptors = [
            item
            for item in FIRST_PARTY_DESCRIPTORS.values()
            if item.credential_policy.state is not ContractState.NOT_APPLICABLE
        ]
    assert descriptors
    assert {
        _PRODUCTION_C_LIVE_DESCRIPTOR_GATE(item.module_id, "team_lead")
        for item in descriptors
    } == {"descriptor_unavailable"}


def test_c_live_production_descriptor_seam_cannot_escape_tests() -> None:
    from ares.modules.descriptors import FIRST_PARTY_DESCRIPTORS

    assert len(FIRST_PARTY_DESCRIPTORS) == 62
    assert _PRODUCTION_C_LIVE_DESCRIPTOR_GATE is not None
    assert all(
        not item.future_gateway_eligible
        and _PRODUCTION_C_LIVE_DESCRIPTOR_GATE(item.module_id, "team_lead")
        == "descriptor_unavailable"
        for item in FIRST_PARTY_DESCRIPTORS.values()
    )


def test_c_live_response_loss_status_inspection_is_stable_and_effect_free() -> None:
    from ares.api.server import _c_live_error_response
    from ares.core.execution_admission import DispatchDispositionV1
    from ares.db.execution_lifecycle import FixedResult

    outcome = _nonterminal_outcome(
        FixedResult.REPLAYED,
        DispatchDispositionV1.REPLAYED,
    )
    first = _c_live_error_response(outcome)
    second = _c_live_error_response(outcome)
    assert first.status_code == second.status_code == 409
    assert json.loads(first.body) == json.loads(second.body)
    assert json.loads(first.body)["redispatched"] is False
    assert json.loads(first.body)["execution"] == {
        "submission_id": "10000000-0000-4000-8000-000000000001",
        "logical_execution_id": "10000000-0000-4000-8000-000000000002",
        "attempt_id": "10000000-0000-4000-8000-000000000003",
    }


@pytest.mark.asyncio
async def test_c_live_repeated_module_response_preserves_occurrence_and_stable_ids(
    c_live_route: Any,
) -> None:
    client, _db, _app, _engine, install = c_live_route
    coordinator = _RecordingLiveCoordinator()
    install(coordinator)
    response = await client.post(
        "/campaigns/camp-c-live/run",
        json={
            "plan": {
                "stages": [
                    {"name": "repeat", "modules": ["plugin.safe", "plugin.safe"]}
                ]
            },
            "global_params": {},
            "dry_run": False,
        },
        headers=_auth("repeat-user", "operator"),
    )

    assert response.status_code == 200
    children = response.json()["children"]
    assert [item["occurrence"] for item in children] == [0, 1]
    assert [item["module_id"] for item in children] == ["plugin.safe", "plugin.safe"]
    assert children[0]["execution"]["attempt_id"] != children[1]["execution"]["attempt_id"]
    assert {item.idempotency_key for item in coordinator.requests} == {_C_LIVE_TEST_KEY}
    assert len({item.whole_intent_digest for item in coordinator.requests}) == 1


@pytest.mark.parametrize(
    ("role_case", "expected_status"),
    [
        ("operator", 200),
        ("team-lead", 200),
        ("reporter", 403),
        ("recon", 403),
        ("admin-not-synthesized", 401),
    ],
    ids=(
        "operator",
        "team-lead",
        "reporter",
        "recon",
        "admin-not-synthesized",
    ),
)
@pytest.mark.asyncio
async def test_c_live_role_mapping(
    role_case: str,
    expected_status: int,
    c_live_route: Any,
) -> None:
    client, db, _app, engine, _install = c_live_route
    role = {
        "team-lead": "team_lead",
        "admin-not-synthesized": "admin",
    }.get(role_case, role_case)
    db.get_campaign.reset_mock()
    response = await client.post(
        "/modules/plugin.safe/run",
        json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
        headers=_auth(f"role-{role_case}", role),
    )

    assert response.status_code == expected_status
    engine.run_module.assert_not_awaited()
    if expected_status != 200:
        db.get_campaign.assert_not_awaited()


@pytest.mark.parametrize(
    "case",
    [
        "applied",
        "replayed",
        "changed-conflict",
        "invalid-contract",
        "conflict-state",
        "authority-stale",
        "capacity-failure",
        "terminal-policy-outcome",
        "settlement-pending",
        "descriptor-unavailable",
    ],
)
@pytest.mark.asyncio
async def test_c_live_http_result_mapping(case: str, c_live_route: Any) -> None:
    from ares.api.server import _c_live_error_response, _c_live_unavailable_response
    from ares.core.execution_admission import DispatchDispositionV1
    from ares.db.execution_lifecycle import FixedResult

    client, _db, _app, _engine, install = c_live_route
    if case == "applied":
        install(_RecordingLiveCoordinator())
        response = await client.post(
            "/modules/plugin.safe/run",
            json={"campaign_id": "camp-c-live", "params": {}, "dry_run": False},
            headers=_auth("mapping-applied", "operator"),
        )
        assert response.status_code == 200
        assert "execution" in response.json()
        return
    if case == "descriptor-unavailable":
        response = _c_live_unavailable_response("descriptor_unavailable")
        expected_status, expected_type = 409, "descriptor_unavailable"
    elif case == "invalid-contract":
        coordinator = _RecordingLiveCoordinator()
        install(coordinator)
        response = await client.post(
            "/campaigns/camp-c-live/run",
            json={"plan": {"stages": []}, "global_params": {}, "dry_run": False},
            headers=_auth("mapping-invalid-contract", "operator"),
        )
        assert coordinator.requests == []
        expected_status, expected_type = 422, "invalid_contract"
    else:
        cases = {
            "replayed": (
                FixedResult.REPLAYED,
                DispatchDispositionV1.REPLAYED,
                409,
                "execution_replayed_no_redispatch",
            ),
            "changed-conflict": (
                FixedResult.CONFLICT_OPERATION,
                DispatchDispositionV1.CONFLICT,
                409,
                "idempotency_conflict",
            ),
            "conflict-state": (
                FixedResult.CONFLICT_STATE,
                DispatchDispositionV1.CONFLICT,
                409,
                "execution_not_dispatchable",
            ),
            "authority-stale": (
                FixedResult.AUTHORITY_STALE,
                DispatchDispositionV1.NON_DISPATCHABLE,
                409,
                "execution_authority_stale",
            ),
            "capacity-failure": (
                FixedResult.CAPACITY_UNAVAILABLE,
                DispatchDispositionV1.NON_DISPATCHABLE,
                429,
                "execution_capacity_unavailable",
            ),
            "terminal-policy-outcome": (
                FixedResult.APPLIED,
                DispatchDispositionV1.NON_DISPATCHABLE,
                409,
                "execution_not_dispatchable",
            ),
            "settlement-pending": (
                FixedResult.APPLIED,
                DispatchDispositionV1.INDETERMINATE,
                503,
                "execution_settlement_unconfirmed",
            ),
        }
        result, disposition, expected_status, expected_type = cases[case]
        response = _c_live_error_response(_nonterminal_outcome(result, disposition))
    if isinstance(response, httpx.Response):
        payload = response.json()
    elif isinstance(response, JSONResponse):
        payload = json.loads(response.body)
    else:
        raise AssertionError(
            "unsupported response type: "
            f"{type(response).__module__}.{type(response).__qualname__}"
        )
    assert response.status_code == expected_status
    assert payload["detail"] == payload["type"] == expected_type
    assert payload["redispatched"] is False


class TestModuleRunEndpoint:
    def setup_method(self) -> None:
        _reset_rate_limiter()

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_module_dry_run_returns_redacted_stable_contract(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine
        from ares.core.engine import AresEngine

        engine = AresEngine(settings=_settings())
        engine.load_modules()
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-dry-run-contract",
            "name": "Dry Run Contract",
            "client": "Internal",
            "operator": "admin",
            "noise_profile": "normal",
            "status": "created",
            "scope_json": '[{"cidr": "10.0.0.0/8", "description": ""}]',
            "targets_json": '["10.0.0.5"]',
            "notes": "",
            "created_at": "2026-06-27 02:15:19",
            "updated_at": "2026-06-27 02:15:19",
        }
        app.dependency_overrides[get_engine] = lambda: engine
        try:
            r = await c.post(
                "/modules/ad.kerberoast/run",
                json={
                    "campaign_id": "camp-dry-run-contract",
                    "params": {
                        "dc": "10.0.0.5",
                        "domain": "corp.local",
                        "username": "svc-roast",
                        "password": "Passw0rd!",
                        "target_user": "sqlsvc",
                    },
                    "dry_run": True,
                },
                headers=_auth("admin", "team_lead"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert r.status_code == 200
        payload = r.json()
        assert payload["status"] == "dry_run_ok"
        assert payload["module_id"] == "ad.kerberoast"
        assert payload["missing_params"] == []
        assert payload["validated_params_summary"]["password"] == "[redacted]"
        assert "Passw0rd!" not in r.text
        assert payload["would_execute"] is True

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_module_run_uses_persisted_campaign_scope_json(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        captured: dict[str, Any] = {}

        class FakeRegistry:
            def get(self, module_id: str) -> Any:
                return object

        class FakeResult:
            findings: list[Any] = []
            status = "success"

            def model_dump(self) -> dict[str, Any]:
                return {
                    "module_id": "demo.scope_capture",
                    "status": "success",
                    "findings": [],
                    "validation_results": [],
                    "raw_output": {},
                    "error": "",
                    "duration_ms": 0,
                }

        class FakeEngine:
            registry = FakeRegistry()

            async def run_module(
                self,
                module_id: str,
                campaign: Any,
                params: dict[str, Any],
                actor_role: str = "",
            ) -> FakeResult:
                captured["campaign"] = campaign
                captured["params"] = params
                captured["actor_role"] = actor_role
                return FakeResult()

        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-scope-json",
            "name": "Scope JSON",
            "client": "Internal",
            "operator": "admin",
            "noise_profile": "stealth",
            "status": "created",
            "scope_json": '[{"cidr": "127.0.0.1/32", "description": ""}]',
            "targets_json": '["127.0.0.1"]',
            "notes": "",
            "created_at": "2026-06-27 02:15:19",
            "updated_at": "2026-06-27 02:15:19",
        }
        app.dependency_overrides[get_engine] = lambda: FakeEngine()
        try:
            r = await c.post(
                "/modules/demo.scope_capture/run",
                json={
                    "campaign_id": "camp-scope-json",
                    "params": {"target": "127.0.0.1"},
                    "dry_run": False,
                },
                headers=_auth("admin", "team_lead"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert r.status_code == 200
        campaign = captured["campaign"]
        assert [entry.cidr for entry in campaign.scope] == ["127.0.0.1/32"]
        assert campaign.targets == ["127.0.0.1"]

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_kerberoast_dashboard_payload_passes_api_validation(self, aclient: Any) -> None:
        c, db, app = aclient
        from ares.api.server import get_c_live_runtime, get_engine
        from ares.modules.ad.kerberoast import KerberoastModule

        captured: dict[str, Any] = {}
        registry_calls: list[str] = []

        class FakeRegistry:
            def get(self, module_id: str) -> Any:
                registry_calls.append(module_id)
                return KerberoastModule if module_id == "ad.kerberoast" else None

        class FakeResult:
            findings: list[Any] = []
            status = "success"

            def model_dump(self) -> dict[str, Any]:
                return {
                    "module_id": "ad.kerberoast",
                    "status": "success",
                    "findings": [],
                    "validation_results": [],
                    "raw_output": {"reached": True},
                    "error": "",
                    "duration_ms": 0,
                }

        class FakeEngine:
            registry = FakeRegistry()

            async def run_module(
                self,
                module_id: str,
                campaign: Any,
                params: dict[str, Any],
                actor_role: str = "",
            ) -> FakeResult:
                captured["module_id"] = module_id
                captured["params"] = params
                captured["actor_role"] = actor_role
                return FakeResult()

        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-kerberoast",
            "name": "Kerberoast API",
            "client": "Internal",
            "operator": "admin",
            "noise_profile": "normal",
            "status": "created",
            "scope_json": '[{"cidr": "10.0.0.0/8", "description": ""}]',
            "targets_json": '["10.0.0.5"]',
            "notes": "",
            "created_at": "2026-06-27 02:15:19",
            "updated_at": "2026-06-27 02:15:19",
        }
        runtime = MagicMock()
        original_runtime = app.dependency_overrides[get_c_live_runtime]
        app.dependency_overrides[get_engine] = lambda: FakeEngine()
        app.dependency_overrides[get_c_live_runtime] = lambda: runtime
        try:
            with patch(
                "ares.api.server._broadcast_event",
                new_callable=AsyncMock,
            ) as broadcast:
                r = await c.post(
                    "/modules/ad.kerberoast/run",
                    json={
                        "campaign_id": "camp-kerberoast",
                        "params": {
                            "dc": "10.0.0.5",
                            "domain": "corp.local",
                            "username": "svc-roast",
                            "password": "Passw0rd!",
                            "use_ldaps": False,
                            "target_user": "sqlsvc",
                        },
                        "dry_run": False,
                    },
                    headers=_auth("admin", "team_lead"),
                )
        finally:
            app.dependency_overrides.pop(get_engine, None)
            app.dependency_overrides[get_c_live_runtime] = original_runtime

        assert r.status_code == 422
        assert r.json() == {
            "code": 422,
            "detail": "raw_secret_material_forbidden",
            "type": "api_error",
        }
        assert "Passw0rd!" not in r.text
        assert captured == {}
        assert registry_calls == []
        runtime.bind.assert_not_called()
        broadcast.assert_not_awaited()

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_module_result_redacts_sensitive_hash_evidence(
        self, aclient: Any
    ) -> None:
        c, db, app = aclient
        from ares.api.server import get_engine

        full_asrep = "[email protected]:abcdef123456"
        full_tgs = "$krb5tgs$23$*svc-sql$LAB.LOCAL$svc/sql*abcdef123456"

        class FakeRegistry:
            def get(self, module_id: str) -> Any:
                return object

        class FakeResult:
            findings: list[Any] = []
            status = "done"
            duration_ms = 1.0

            def model_dump(self) -> dict[str, Any]:
                return {
                    "module_id": "demo.hash_output",
                    "status": "done",
                    "findings": [
                        {
                            "evidence": {
                                "hash_count": 2,
                                "sample_hash": full_asrep,
                            }
                        }
                    ],
                    "validation_results": [],
                    "raw_output": {
                        "asrep_hashes": [full_asrep],
                        "kerberos_hashes": [full_tgs],
                        "accounts": [{"name": "svc-sql", "hash": full_tgs}],
                        "hash_count": 2,
                    },
                    "error": "",
                    "duration_ms": self.duration_ms,
                }

        class FakeEngine:
            registry = FakeRegistry()

            async def run_module(
                self,
                module_id: str,
                campaign: Any,
                params: dict[str, Any],
                actor_role: str = "",
            ) -> FakeResult:
                return FakeResult()

        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": "camp-hash-output",
            "name": "Hash Output",
            "client": "Internal",
            "operator": "admin",
            "noise_profile": "normal",
            "scope_json": '[{"cidr": "10.0.0.0/8", "description": ""}]',
            "targets_json": '["10.0.0.5"]',
            "status": "created",
        }
        app.dependency_overrides[get_engine] = lambda: FakeEngine()
        try:
            response = await c.post(
                "/modules/demo.hash_output/run",
                json={
                    "campaign_id": "camp-hash-output",
                    "params": {"target": "10.0.0.5"},
                    "dry_run": False,
                },
                headers=_auth("admin", "team_lead"),
            )
        finally:
            app.dependency_overrides.pop(get_engine, None)

        assert response.status_code == 200
        payload = response.json()
        assert full_asrep not in response.text
        assert full_tgs not in response.text
        assert payload["raw_output"]["hash_count"] == 2
        assert payload["raw_output"]["asrep_hashes"] == "[REDACTED sensitive evidence]"
        assert payload["raw_output"]["kerberos_hashes"] == "[REDACTED sensitive evidence]"
        assert payload["findings"][0]["evidence"]["sample_hash"] == "[REDACTED sensitive evidence]"

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_module_run_updates_telemetry_snapshot(
        self, aclient: Any, monkeypatch: Any
    ) -> None:
        c, db, app = aclient
        import ares.telemetry.collector as telemetry
        from ares.api.server import get_engine

        telemetry._global_collector = telemetry.TelemetryCollector()

        class FakeRegistry:
            def get(self, module_id: str) -> Any:
                return object

        class FakeFinding:
            false_positive = False
            severity = "low"
            cvss_score = 0.0
            cvss_vector = ""
            trace_id = ""

        class FakeResult:
            findings: list[Any] = [FakeFinding()]
            status = "done"
            outcome = "confirmed_findings"
            duration_ms = 42.5

            def model_dump(self) -> dict[str, Any]:
                return {
                    "module_id": "demo.telemetry",
                    "status": "done",
                    "findings": [],
                    "validation_results": [],
                    "raw_output": {},
                    "error": "",
                    "duration_ms": self.duration_ms,
                    "outcome": self.outcome,
                }

        class FakeEngine:
            registry = FakeRegistry()

            async def run_module(
                self,
                module_id: str,
                campaign: Any,
                params: dict[str, Any],
                actor_role: str = "",
            ) -> FakeResult:
                return FakeResult()

        db.is_access_token_revoked.return_value = False
        db.save_finding = AsyncMock()
        db.record_module_run.reset_mock()
        db.get_telemetry_stats.return_value = {
            "modules": {"total": 1, "success": 1, "failed": 0, "error_rate": 0.0},
            "findings": 1,
            "latency_ms": {"p50": 42.5, "p95": 42.5, "p99": 42.5},
            "throughput": {"tasks_per_min": 1.0},
            "hosts": {"available": False, "discovered": 0, "owned": None},
        }
        db.get_campaign.return_value = {
            "id": "camp-telemetry",
            "name": "Telemetry",
            "client": "Internal",
            "operator": "admin",
            "noise_profile": "stealth",
            "status": "created",
            "scope_json": '[{"cidr": "127.0.0.1/32", "description": ""}]',
            "targets_json": '["127.0.0.1"]',
            "notes": "",
            "created_at": "2026-06-27 02:15:19",
            "updated_at": "2026-06-27 02:15:19",
        }
        monkeypatch.setattr(
            "ares.api.server.enrich_finding_with_cvss",
            lambda finding: finding,
            raising=False,
        )
        app.dependency_overrides[get_engine] = lambda: FakeEngine()
        try:
            r = await c.post(
                "/modules/demo.telemetry/run",
                json={
                    "campaign_id": "camp-telemetry",
                    "params": {"target": "127.0.0.1"},
                    "dry_run": False,
                },
                headers=_auth("admin", "team_lead"),
            )
            t = await c.get("/telemetry", headers=_auth("admin", "team_lead"))
        finally:
            app.dependency_overrides.pop(get_engine, None)
            telemetry._global_collector = None

        assert r.status_code == 200
        assert t.status_code == 200
        snapshot = t.json()
        assert snapshot["modules"]["total"] == 1
        assert snapshot["modules"]["success"] == 1
        assert snapshot["findings"] == 1
        assert snapshot["latency_ms"]["p50"] == 42.5
        # Persistence belongs to the DB-bound engine.  A lightweight route
        # double must not cause the API layer to write a second record.
        db.record_module_run.assert_not_awaited()
        db.save_finding.assert_not_awaited()


class TestReportEndpoints:
    def setup_method(self) -> None:
        _reset_rate_limiter()

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_reports_list_only_campaign_prefixed_files(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())
        owned = tmp_path / f"{campaign_id}_Acme_20260101_0000.html"
        other = tmp_path / "other_Acme_20260101_0000.html"
        owned.write_text("owned", encoding="utf-8")
        other.write_text("other", encoding="utf-8")
        r = await c.get(f"/reports/{campaign_id}", headers=_auth("admin", "team_lead"))
        assert r.status_code == 200
        filenames = [item["filename"] for item in r.json()["reports"]]
        assert filenames == [owned.name]

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_generate_json_report_hydrates_confirmed_db_findings(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.modules.reporting.report_gen as report_gen

        real_report_generator = report_gen.ReportGenerator
        campaign_id = "camp-ad-lab"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "AD Lab Attack Simulation",
            "client": "Internal",
            "operator": "admin",
            "noise_profile": "normal",
            "status": "created",
            "scope_json": '[{"cidr": "10.10.10.0/24", "description": "AD lab"}]',
            "targets_json": '["10.10.10.20"]',
            "notes": "",
        }
        db.list_findings.return_value = (
            [
                {
                    "id": "finding-asrep",
                    "campaign_id": campaign_id,
                    "module_id": "ad.asreproast",
                    "title": "ASREPRoast Hashes Captured (1)",
                    "description": "Captured one AS-REP hash.",
                    "severity": "high",
                    "confidence": 1.0,
                    "mitre_technique": "T1558.004",
                    "mitre_tactic": "Credential Access",
                    "evidence_json": '{"hash_count": 1, "sample_hash": "[email protected]:abcdef"}',
                    "remediation": "Require Kerberos pre-authentication.",
                    "host": "10.10.10.20",
                    "validated": 0,
                    "false_positive": 0,
                    "discovered_at": "2026-07-12T01:00:00+00:00",
                },
                {
                    "id": "finding-kerb",
                    "campaign_id": campaign_id,
                    "module_id": "ad.kerberoast",
                    "title": "Kerberoast Hashes Captured (1)",
                    "description": "Captured one TGS hash.",
                    "severity": "critical",
                    "confidence": 1.0,
                    "mitre_technique": "T1558.003",
                    "mitre_tactic": "Credential Access",
                    "evidence_json": '{"hash_count": 1, "accounts": ["svc-sql"], "sample_hash": "$krb5tgs$23$*svc-sql$LAB.LOCAL$svc/sql*abcdef"}',
                    "remediation": "Rotate service account credentials.",
                    "host": "10.10.10.20",
                    "validated": 0,
                    "false_positive": 0,
                    "discovered_at": "2026-07-12T01:01:00+00:00",
                },
            ],
            2,
        )

        def generator_factory(*args: Any, **kwargs: Any) -> Any:
            return real_report_generator(output_dir=str(tmp_path), **kwargs)

        monkeypatch.setattr(report_gen, "ReportGenerator", generator_factory)

        r = await c.post(
            f"/reports/{campaign_id}?fmt=json",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 200
        path = tmp_path / r.json()["filename"]
        assert path.exists()
        data = __import__("json").loads(path.read_text(encoding="utf-8"))
        assert data["summary"]["total_confirmed"] == 2
        assert data["summary"]["by_severity"]["high"] == 1
        assert data["summary"]["by_severity"]["critical"] == 1
        assert data["summary"]["by_module"]["ad.asreproast"] == 1
        assert data["summary"]["by_module"]["ad.kerberoast"] == 1
        assert data["findings"]
        assert data["key_findings"]
        assert data["campaign"]["targets"] == ["10.10.10.20"]
        assert data["campaign"]["scope"][0]["cidr"] == "10.10.10.0/24"
        assert "$krb5asrep$" not in path.read_text(encoding="utf-8")
        assert "$krb5tgs$" not in path.read_text(encoding="utf-8")
        assert "validated" not in db.list_findings.await_args.kwargs
        assert db.list_findings.await_args.kwargs["false_positive"] is False

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_dashboard_run_findings_and_report_use_same_persisted_db_path(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, _, app = aclient
        import ares.modules.reporting.report_gen as report_gen
        from ares.api.server import get_c_live_runtime, get_db, get_engine
        from ares.core.campaign import Campaign, Finding, NoiseProfile, ScopeEntry, Severity
        from ares.core.engine import EngineModuleResult, ModuleStatus
        from ares.core.security import create_access_token
        from ares.db.database import AresDatabase

        real_report_generator = report_gen.ReportGenerator
        real_db = await AresDatabase.create(tmp_path / "ares.db")
        await real_db.create_user(
            "admin",
            "SyntheticReportPrincipal1!",
            "team_lead",
        )
        issued = await real_db.create_login_session(
            "admin",
            "SyntheticReportPrincipal1!",
            lambda claims: create_access_token(
                dict(claims),
                _settings().secret_key_value,
            ),
        )
        assert issued.session is not None
        real_auth = {
            "Authorization": f"Bearer {issued.session.access_token}",
            "Idempotency-Key": _C_LIVE_TEST_KEY,
        }
        original_db = getattr(app.state, "db", None)
        campaign = Campaign(
            name="AD Lab Attack Simulation",
            client="Internal",
            operator="admin",
            targets=["10.10.10.20"],
            scope=[ScopeEntry(cidr="10.10.10.0/24")],
            noise_profile=NoiseProfile.NORMAL,
        )
        await real_db.save_campaign(campaign)

        registry_calls: list[str] = []
        module_calls: list[str] = []

        def finding_for(module_id: str) -> Finding:
            if module_id == "ad.asreproast":
                return Finding(
                    title="ASREPRoast Hashes Captured (1)",
                    description="Captured one AS-REP hash.",
                    severity=Severity.HIGH,
                    validated=True,
                    module_id=module_id,
                    mitre_technique="T1558.004",
                    mitre_tactic="Credential Access",
                    evidence={
                        "hash_count": 1,
                        "sample_hash": "[email protected]:abcdef",
                    },
                    remediation="Require Kerberos pre-authentication.",
                    host="10.10.10.20",
                )
            return Finding(
                title="Kerberoast Hashes Captured (1)",
                description="Captured one TGS hash.",
                severity=Severity.CRITICAL,
                validated=True,
                module_id=module_id,
                mitre_technique="T1558.003",
                mitre_tactic="Credential Access",
                evidence={
                    "hash_count": 1,
                    "accounts": ["svc-sql"],
                    "sample_hash": "$krb5tgs$23$*svc-sql$LAB.LOCAL$svc/sql*abcdef",
                },
                remediation="Rotate service account credentials.",
                host="10.10.10.20",
            )

        class FakeRegistry:
            def get(self, module_id: str) -> Any:
                registry_calls.append(module_id)
                return None

        class FakeEngine:
            registry = FakeRegistry()

            def __init__(self, db: AresDatabase) -> None:
                self.db = db

            async def run_module(
                self,
                module_id: str,
                campaign: Any,
                params: dict[str, Any],
                actor_role: str = "",
            ) -> EngineModuleResult:
                module_calls.append(module_id)
                finding = finding_for(module_id)
                result = EngineModuleResult(
                    module_id=module_id,
                    status=ModuleStatus.DONE,
                    findings=[finding],
                    raw_output={"confirmed": 1},
                    duration_ms=12.0,
                )
                await self.db.save_finding(campaign.id, finding, module_id)
                await self.db.record_module_run(
                    campaign.id,
                    module_id,
                    result.outcome,
                    True,
                    result.duration_ms,
                )
                return result

        def generator_factory(*args: Any, **kwargs: Any) -> Any:
            return real_report_generator(output_dir=str(tmp_path / "reports"), **kwargs)

        async def effect_counts() -> tuple[int, ...]:
            cursor = await real_db.conn.execute(
                """
                SELECT
                    (SELECT COUNT(*) FROM logical_executions),
                    (SELECT COUNT(*) FROM execution_attempts),
                    (SELECT COUNT(*) FROM execution_publication_outbox),
                    (SELECT COUNT(*) FROM execution_operation_receipts),
                    (SELECT COUNT(*) FROM module_runs),
                    (SELECT COUNT(*) FROM findings)
                """
            )
            row = await cursor.fetchone()
            await cursor.close()
            return tuple(int(value) for value in row)

        runtime = MagicMock()
        original_runtime = app.dependency_overrides[get_c_live_runtime]
        app.state.db = real_db
        app.dependency_overrides[get_db] = lambda: real_db
        app.dependency_overrides[get_engine] = lambda: FakeEngine(real_db)
        app.dependency_overrides[get_c_live_runtime] = lambda: runtime
        monkeypatch.setattr(report_gen, "ReportGenerator", generator_factory)
        try:
            before_effects = await effect_counts()
            assert before_effects == (0, 0, 0, 0, 0, 0)
            common_params = {
                "dc": "10.10.10.20",
                "domain": "lab.local",
                "username": "lab\\operator",
                "password": "CorrectHorseBatteryStaple!",
                "use_ldaps": False,
            }
            with patch(
                "ares.api.server._broadcast_event",
                new_callable=AsyncMock,
            ) as broadcast:
                asrep = await c.post(
                    "/modules/ad.asreproast/run",
                    headers=real_auth,
                    json={
                        "campaign_id": campaign.id,
                        "params": common_params,
                        "dry_run": False,
                    },
                )
                kerb = await c.post(
                    "/modules/ad.kerberoast/run",
                    headers=real_auth,
                    json={
                        "campaign_id": campaign.id,
                        "params": {**common_params, "target_user": "svc-sql"},
                        "dry_run": False,
                    },
                )
            assert asrep.status_code == 422
            assert kerb.status_code == 422
            assert asrep.json() == {
                "code": 422,
                "detail": "raw_secret_material_forbidden",
                "type": "api_error",
            }
            assert kerb.json() == {
                "code": 422,
                "detail": "raw_secret_material_forbidden",
                "type": "api_error",
            }
            assert "CorrectHorseBatteryStaple!" not in asrep.text
            assert "CorrectHorseBatteryStaple!" not in kerb.text
            assert registry_calls == []
            assert module_calls == []
            runtime.bind.assert_not_called()
            broadcast.assert_not_awaited()
            assert await effect_counts() == before_effects

            # Seed equivalent historical rows explicitly after proving the two
            # rejected requests had zero effect, so the persisted report-path
            # assertions below remain independent of the live boundary.
            for module_id in ("ad.asreproast", "ad.kerberoast"):
                finding = finding_for(module_id)
                result = EngineModuleResult(
                    module_id=module_id,
                    status=ModuleStatus.DONE,
                    findings=[finding],
                    raw_output={"confirmed": 1},
                    duration_ms=12.0,
                )
                await real_db.save_finding(campaign.id, finding, module_id)
                await real_db.record_module_run(
                    campaign.id,
                    module_id,
                    result.outcome,
                    True,
                    result.duration_ms,
                )

            # Legacy/current dashboard rows may be visible even if the validated
            # flag is not populated; report hydration must not use a stricter
            # finder than the dashboard list.
            await real_db.conn.execute(
                "UPDATE findings SET validated=0 WHERE campaign_id=?",
                (campaign.id,),
            )
            await real_db.conn.commit()

            findings_response = await c.get(
                f"/campaigns/{campaign.id}/findings",
                headers=real_auth,
            )
            assert findings_response.status_code == 200
            assert len(findings_response.json()) == 2
            assert all(
                row["evidence_json"] == '{"redacted":true}' for row in findings_response.json()
            )
            assert "$krb5asrep$" not in findings_response.text
            assert "$krb5tgs$" not in findings_response.text

            stored_rows, stored_total = await real_db.list_findings(
                campaign.id, page=1, per_page=50
            )
            stored_evidence = [
                __import__("json").loads(row["evidence_json"]) for row in stored_rows
            ]
            assert stored_total == 2
            assert all("sample_hash" in evidence for evidence in stored_evidence)
            assert all(evidence != {"redacted": True} for evidence in stored_evidence)

            report_response = await c.post(
                f"/reports/{campaign.id}?fmt=json",
                headers=real_auth,
            )
        finally:
            app.dependency_overrides.pop(get_db, None)
            app.dependency_overrides.pop(get_engine, None)
            app.dependency_overrides[get_c_live_runtime] = original_runtime
            app.state.db = original_db
            await real_db.close()

        assert report_response.status_code == 200
        path = tmp_path / "reports" / report_response.json()["filename"]
        data = __import__("json").loads(path.read_text(encoding="utf-8"))
        assert data["summary"]["total_confirmed"] == 2
        assert data["summary"]["by_module"]["ad.asreproast"] == 1
        assert data["summary"]["by_module"]["ad.kerberoast"] == 1
        assert data["summary"]["by_severity"]["high"] == 1
        assert data["summary"]["by_severity"]["critical"] == 1
        assert len(data["findings"]) >= 2
        assert len(data["key_findings"]) >= 2
        assert data["campaign"]["targets"] == ["10.10.10.20"]
        assert data["campaign"]["scope"][0]["cidr"] == "10.10.10.0/24"
        assert all(
            finding["evidence"]["sample_hash"] == "[REDACTED sensitive evidence]"
            for finding in data["findings"]
        )
        assert "T1558.003" in path.read_text(encoding="utf-8")
        assert "T1558.004" in path.read_text(encoding="utf-8")
        assert "$krb5asrep$" not in path.read_text(encoding="utf-8")
        assert "$krb5tgs$" not in path.read_text(encoding="utf-8")

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_download_rejects_encoded_traversal(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())
        r = await c.get(
            f"/reports/{campaign_id}/files/%2e%2e%5csecret.html",
            headers=_auth("admin", "team_lead"),
        )
        assert r.status_code == 400

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_download_serves_owned_file(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())
        report = tmp_path / f"{campaign_id}_Acme_20260101_0000.html"
        report.write_text("owned report", encoding="utf-8")
        r = await c.get(
            f"/reports/{campaign_id}/files/{report.name}",
            headers=_auth("admin", "team_lead"),
        )
        assert r.status_code == 200
        assert r.text == "owned report"

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_delete_existing_file_succeeds(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())
        report = tmp_path / f"{campaign_id}_Acme_20260101_0000.pdf"
        report.write_bytes(b"%PDF-1.4\n")

        r = await c.delete(
            f"/reports/{campaign_id}/files/{report.name}",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 200
        assert r.json()["filename"] == report.name
        assert not report.exists()

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_delete_missing_file_returns_404(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())

        r = await c.delete(
            f"/reports/{campaign_id}/files/{campaign_id}_Acme_missing.pdf",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 404

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_delete_rejects_path_traversal(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())

        r = await c.delete(
            f"/reports/{campaign_id}/files/%2e%2e%5csecret.pdf",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 400

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_delete_rejects_absolute_path(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())

        r = await c.delete(
            f"/reports/{campaign_id}/files/C%3A%5Csecret.pdf",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 400

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_delete_rejects_nested_path(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())

        r = await c.delete(
            f"/reports/{campaign_id}/files/nested%5Creport.pdf",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 400

    @pytest.mark.asyncio  # type: ignore[untyped-decorator]
    async def test_report_delete_bulk_deletes_only_allowed_campaign_artifacts(
        self, aclient: Any, tmp_path: Any, monkeypatch: Any
    ) -> None:
        c, db, _ = aclient
        import ares.api.server as server

        campaign_id = "camp-123"
        db.is_access_token_revoked.return_value = False
        db.get_campaign.return_value = {
            "id": campaign_id,
            "name": "Acme",
            "operator": "admin",
        }
        monkeypatch.setattr(server, "_report_root", lambda: tmp_path.resolve())
        owned_pdf = tmp_path / f"{campaign_id}_Acme_20260101_0000.pdf"
        owned_json = tmp_path / f"{campaign_id}_Acme_20260101_0000.json"
        owned_html = tmp_path / f"{campaign_id}_Acme_20260101_0000.html"
        owned_md = tmp_path / f"{campaign_id}_Acme_20260101_0000.md"
        owned_txt = tmp_path / f"{campaign_id}_Acme_20260101_0000.txt"
        other = tmp_path / "other_Acme_20260101_0000.pdf"
        report_dir = tmp_path / f"{campaign_id}_Acme_20260101_0000.pdf.dir"
        report_dir.mkdir()
        for path in (owned_pdf, owned_json, owned_html, owned_md, owned_txt, other):
            path.write_text("artifact", encoding="utf-8")

        r = await c.delete(
            f"/reports/{campaign_id}",
            headers=_auth("admin", "team_lead"),
        )

        assert r.status_code == 200
        assert r.json()["deleted"] == 4
        assert not owned_pdf.exists()
        assert not owned_json.exists()
        assert not owned_html.exists()
        assert not owned_md.exists()
        assert owned_txt.exists()
        assert other.exists()
        assert report_dir.exists()


class TestAuthoritativeHTTPBearerPrincipal:
    @pytest.fixture
    async def auth_runtime(self, tmp_path: Any):
        from ares.api.server import app, get_db
        from ares.core.security import create_access_token
        from ares.db import database as database_module
        from ares.db.database import AresDatabase

        database = await AresDatabase.create(tmp_path / "http-principal.db")
        username = "http-principal-user"
        with patch.object(database_module.logger, "info"):
            user_id = await database.create_user(
                username,
                "SyntheticPrincipalPass1!",
                "team_lead",
            )
        issued = await database.create_login_session(
            username,
            "SyntheticPrincipalPass1!",
            lambda claims: create_access_token(
                dict(claims),
                _settings().secret_key_value,
            ),
        )
        assert issued.session is not None
        token = issued.session.access_token
        original_db = getattr(app.state, "db", None)
        original_overrides = dict(app.dependency_overrides)
        app.state.db = database
        app.dependency_overrides[get_db] = lambda: database
        client = httpx.AsyncClient(
            transport=httpx.ASGITransport(app=app),
            base_url="http://localhost",
        )
        try:
            yield client, database, user_id, username, token, app
        finally:
            await client.aclose()
            app.dependency_overrides.clear()
            app.dependency_overrides.update(original_overrides)
            app.state.db = original_db
            await database.close()

    @staticmethod
    def _bearer_headers(token: str) -> dict[str, str]:
        return {"Authorization": f"Bearer {token}"}

    @staticmethod
    def _signed_token(payload: dict[str, Any]) -> str:
        import jwt

        settings = _settings()
        return jwt.encode(
            payload,
            settings.secret_key_value,
            algorithm=settings.ares_jwt_algorithm,
        )

    @pytest.mark.asyncio
    async def test_active_inactive_reactivation_rename_and_delete(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, user_id, username, token, _ = auth_runtime
        _reset_rate_limiter()

        active_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        active_body = active_response.json()
        _require_fixed(
            active_response.status_code == 200
            and active_body.get("username") == username
            and active_body.get("role") == "team_lead",
            "expected an active bearer principal to reach the protected handler",
        )

        await database.apply_user_security_event(
            user_id=user_id,
            reason="user_status_change",
            is_active=False,
        )
        inactive_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        inactive_body = inactive_response.json()
        _require_fixed(
            inactive_response.status_code == 401
            and inactive_body.get("detail") == "Not authenticated"
            and "inactive" not in str(inactive_body).lower(),
            "expected an inactive bearer principal to receive the generic failure",
        )

        list_calls = [0]
        original_list_users = database.list_users

        async def tracked_list_users() -> list[dict[str, Any]]:
            list_calls[0] += 1
            return await original_list_users()

        database.list_users = tracked_list_users  # type: ignore[method-assign]
        inactive_elevated_response = await client.get(
            "/security/users",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            inactive_elevated_response.status_code == 401 and list_calls[0] == 0,
            "expected inactive bearer denial before protected handler work",
        )

        await database.apply_user_security_event(
            user_id=user_id,
            reason="user_status_change",
            is_active=True,
        )
        reactivated_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            reactivated_response.status_code == 401,
            "expected status-change epoch revocation to remain authoritative",
        )

        await database.conn.execute(
            "UPDATE users SET username=? WHERE id=?",
            ("renamed-http-principal", user_id),
        )
        await database.conn.commit()
        renamed_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            renamed_response.status_code == 401,
            "expected a token with a stale renamed subject to be rejected",
        )

        await database.conn.execute("DELETE FROM users WHERE id=?", (user_id,))
        await database.conn.commit()
        deleted_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            deleted_response.status_code == 401
            and deleted_response.json().get("detail") == "Not authenticated",
            "expected a deleted bearer principal to receive the generic failure",
        )

    @pytest.mark.asyncio
    async def test_current_database_role_controls_403_and_promotion(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, user_id, _username, token, _ = auth_runtime
        _reset_rate_limiter()
        list_calls = [0]
        original_list_users = database.list_users

        async def tracked_list_users() -> list[dict[str, Any]]:
            list_calls[0] += 1
            return await original_list_users()

        database.list_users = tracked_list_users  # type: ignore[method-assign]
        await database.conn.execute(
            "UPDATE users SET role='operator' WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        demoted_response = await client.get(
            "/security/users",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            demoted_response.status_code == 403 and list_calls[0] == 0,
            "expected current demoted role to block team-lead work",
        )

        await database.conn.execute(
            "UPDATE users SET role='team_lead' WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        promoted_response = await client.get(
            "/security/users",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            promoted_response.status_code == 200 and list_calls[0] == 1,
            "expected current promoted role to authorize the next request",
        )

        await database.conn.execute(
            "UPDATE users SET role='unsupported-role' WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        invalid_role_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            invalid_role_response.status_code == 401,
            "expected an unknown database role to fail authentication",
        )

    @pytest.mark.asyncio
    async def test_revoked_jti_is_generic_401(
        self,
        auth_runtime: Any,
    ) -> None:
        from ares.core.security import decode_access_token

        client, database, user_id, _, token, _ = auth_runtime
        settings = _settings()
        payload = decode_access_token(
            token,
            settings.secret_key_value,
            settings.ares_jwt_algorithm,
        )
        payload_valid = isinstance(payload, dict)
        _require_fixed(payload_valid, "expected the test bearer token to decode")
        jti = payload.get("jti") if payload else None
        jti_valid = isinstance(jti, str) and bool(jti.strip())
        _require_fixed(jti_valid, "expected the test bearer token to contain a JTI")
        await database.revoke_access_token(
            jti,
            user_id,
            "2099-01-01 00:00:00",
        )
        response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        body = response.json()
        _require_fixed(
            response.status_code == 401
            and body.get("detail") == "Not authenticated"
            and "revoked" not in str(body).lower(),
            "expected a revoked bearer token to receive the generic failure",
        )

    @pytest.mark.parametrize(
        ("_case", "claims"),
        [
            ("missing-sub", {"jti": "claim-jti", "exp": 4102444800}),
            ("empty-sub", {"sub": "", "jti": "claim-jti", "exp": 4102444800}),
            ("blank-sub", {"sub": "   ", "jti": "claim-jti", "exp": 4102444800}),
            ("numeric-sub", {"sub": 7, "jti": "claim-jti", "exp": 4102444800}),
            ("missing-jti", {"sub": "claim-user", "exp": 4102444800}),
            ("empty-jti", {"sub": "claim-user", "jti": "", "exp": 4102444800}),
            ("blank-jti", {"sub": "claim-user", "jti": "   ", "exp": 4102444800}),
            ("object-jti", {"sub": "claim-user", "jti": {}, "exp": 4102444800}),
            ("missing-exp", {"sub": "claim-user", "jti": "claim-jti"}),
            (
                "string-exp",
                {"sub": "claim-user", "jti": "claim-jti", "exp": "4102444800"},
            ),
            (
                "boolean-exp",
                {"sub": "claim-user", "jti": "claim-jti", "exp": True},
            ),
        ],
        ids=lambda value: value if isinstance(value, str) else None,
    )
    @pytest.mark.asyncio
    async def test_mandatory_claim_failures_do_not_query_database(
        self,
        auth_runtime: Any,
        _case: str,
        claims: dict[str, Any],
    ) -> None:
        client, database, _, _, _, _ = auth_runtime
        _reset_rate_limiter()
        calls = [0]
        original_resolve = database.resolve_access_token_principal

        async def tracked_resolve(subject: str, jti: str) -> dict[str, Any] | None:
            calls[0] += 1
            return await original_resolve(subject, jti)

        database.resolve_access_token_principal = tracked_resolve  # type: ignore[method-assign]
        token = self._signed_token(claims)
        response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        body = response.json()
        _require_fixed(
            response.status_code == 401
            and body.get("detail") == "Not authenticated"
            and response.headers.get("www-authenticate") == "Bearer"
            and calls[0] == 0,
            "expected fixed mandatory-claim validation failure",
        )

    @pytest.mark.parametrize(
        "_case",
        [
            "object",
            "list",
            "null",
            "positive-infinity",
            "negative-infinity",
            "nan",
            "oversized-integer",
        ],
    )
    @pytest.mark.asyncio
    async def test_malformed_exp_is_generic_401_before_database_or_handler(
        self,
        auth_runtime: Any,
        _case: str,
    ) -> None:
        client, database, _, username, _, _ = auth_runtime
        _reset_rate_limiter()
        principal_calls = [0]
        handler_calls = [0]
        original_resolve = database.resolve_access_token_principal
        original_list_users = database.list_users

        async def tracked_resolve(subject: str, jti: str) -> dict[str, Any] | None:
            principal_calls[0] += 1
            return await original_resolve(subject, jti)

        async def tracked_list_users() -> list[dict[str, Any]]:
            handler_calls[0] += 1
            return await original_list_users()

        database.resolve_access_token_principal = tracked_resolve  # type: ignore[method-assign]
        database.list_users = tracked_list_users  # type: ignore[method-assign]
        malformed_exp_by_case: dict[str, Any] = {
            "object": {},
            "list": [],
            "null": None,
            "positive-infinity": float("inf"),
            "negative-infinity": float("-inf"),
            "nan": float("nan"),
            "oversized-integer": 10**400,
        }
        token = self._signed_token(
            {
                "sub": username,
                "jti": "malformed-exp-jti",
                "exp": malformed_exp_by_case[_case],
            }
        )
        response = await client.get(
            "/security/users",
            headers=self._bearer_headers(token),
        )
        body = response.json()
        body_text = str(body).lower()
        _require_fixed(
            response.status_code == 401 and response.status_code != 500,
            "expected malformed expiry to return the generic authentication status",
        )
        _require_fixed(
            body.get("detail") == "Not authenticated"
            and "typeerror" not in body_text
            and "overflowerror" not in body_text
            and "valueerror" not in body_text,
            "expected malformed expiry to return the generic authentication envelope",
        )
        _require_fixed(
            response.headers.get("www-authenticate") == "Bearer",
            "expected malformed expiry to retain the bearer challenge",
        )
        _require_fixed(
            principal_calls[0] == 0,
            "expected malformed expiry to fail before database principal lookup",
        )
        _require_fixed(
            handler_calls[0] == 0,
            "expected malformed expiry to fail before protected handler work",
        )

    @pytest.mark.asyncio
    async def test_expired_and_malformed_bearer_are_generic_401(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, _, username, _, _ = auth_runtime
        _reset_rate_limiter()
        calls = [0]
        original_resolve = database.resolve_access_token_principal

        async def tracked_resolve(subject: str, jti: str) -> dict[str, Any] | None:
            calls[0] += 1
            return await original_resolve(subject, jti)

        database.resolve_access_token_principal = tracked_resolve  # type: ignore[method-assign]
        from ares.core.security import create_access_token

        settings = _settings()
        expired = create_access_token(
            {"sub": username, "role": "team_lead"},
            settings.secret_key_value,
            algorithm=settings.ares_jwt_algorithm,
            expires_minutes=-1,
        )
        expired_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(expired),
        )
        malformed_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers("synthetic.invalid.jwt"),
        )
        _require_fixed(
            expired_response.status_code == 401
            and malformed_response.status_code == 401
            and calls[0] == 0,
            "expected expired and malformed bearers to fail before DB authorization",
        )

    @pytest.mark.asyncio
    async def test_closed_database_is_503_and_recovery_succeeds_without_handler_work(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, _, _, token, _ = auth_runtime
        _reset_rate_limiter()
        list_calls = [0]
        original_list_users = database.list_users

        async def tracked_list_users() -> list[dict[str, Any]]:
            list_calls[0] += 1
            return await original_list_users()

        database.list_users = tracked_list_users  # type: ignore[method-assign]
        await database.close()
        unavailable_response = await client.get(
            "/security/users",
            headers=self._bearer_headers(token),
        )
        unavailable_body = unavailable_response.json()
        _require_fixed(
            unavailable_response.status_code == 503
            and unavailable_body.get("detail") == "Authentication service unavailable"
            and unavailable_response.headers.get("www-authenticate") is None
            and list_calls[0] == 0,
            "expected a closed auth database to deny work with fixed 503",
        )

        await database.connect()
        recovered_response = await client.get(
            "/security/users",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            recovered_response.status_code == 200 and list_calls[0] == 1,
            "expected a recovered auth database to authorize a subsequent request",
        )

    @pytest.mark.asyncio
    async def test_absent_and_timeout_database_are_fixed_503(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, _, _, token, app = auth_runtime
        _reset_rate_limiter()
        app.state.db = None
        absent_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        _require_fixed(
            absent_response.status_code == 503
            and absent_response.json().get("detail")
            == "Authentication service unavailable"
            and absent_response.headers.get("www-authenticate") is None,
            "expected absent auth database to map to fixed 503",
        )

        app.state.db = database

        async def fail_lookup(_subject: str, _jti: str) -> dict[str, Any] | None:
            raise TimeoutError

        database.resolve_access_token_principal = fail_lookup  # type: ignore[method-assign]
        timeout_response = await client.get(
            "/auth/me",
            headers=self._bearer_headers(token),
        )
        timeout_body = timeout_response.json()
        _require_fixed(
            timeout_response.status_code == 503
            and timeout_body.get("detail") == "Authentication service unavailable"
            and timeout_response.headers.get("www-authenticate") is None
            and "timeout" not in str(timeout_body).lower(),
            "expected auth lookup timeout to map to sanitized fixed 503",
        )

    @pytest.mark.asyncio
    async def test_api_key_outage_is_503_invalid_key_is_401_and_bearer_wins(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, user_id, _, token, _ = auth_runtime
        _reset_rate_limiter()
        _, raw_key = await database.create_api_key(user_id, "http-outage-key")
        verify_calls = [0]
        original_verify = database.verify_api_key

        async def tracked_verify(candidate: str) -> dict[str, Any] | None:
            verify_calls[0] += 1
            return await original_verify(candidate)

        database.verify_api_key = tracked_verify  # type: ignore[method-assign]
        await database.close()
        api_key_response = await client.get(
            "/auth/me",
            headers={"X-API-Key": raw_key},
        )
        _require_fixed(
            api_key_response.status_code == 503
            and api_key_response.json().get("detail")
            == "Authentication service unavailable"
            and verify_calls[0] == 1,
            "expected API-key database outage to map to fixed 503",
        )

        verify_calls[0] = 0
        precedence_response = await client.get(
            "/auth/me",
            headers={
                "Authorization": f"Bearer {token}",
                "X-API-Key": raw_key,
            },
        )
        _require_fixed(
            precedence_response.status_code == 503 and verify_calls[0] == 0,
            "expected bearer backend outage not to fall through to API-key auth",
        )

        await database.connect()
        invalid_response = await client.get(
            "/auth/me",
            headers={"X-API-Key": "ares_invalid_synthetic_key"},
        )
        _require_fixed(
            invalid_response.status_code == 401
            and invalid_response.json().get("detail")
            == "Not authenticated. Provide Bearer token or X-API-Key.",
            "expected invalid API key to retain the generic 401 contract",
        )

    @pytest.mark.asyncio
    async def test_invalid_explicit_bearer_does_not_fall_through_to_api_key(
        self,
        auth_runtime: Any,
    ) -> None:
        client, database, user_id, _, _, _ = auth_runtime
        _reset_rate_limiter()
        _, raw_key = await database.create_api_key(user_id, "precedence-key")
        verify_calls = [0]
        original_verify = database.verify_api_key

        async def tracked_verify(candidate: str) -> dict[str, Any] | None:
            verify_calls[0] += 1
            return await original_verify(candidate)

        database.verify_api_key = tracked_verify  # type: ignore[method-assign]
        response = await client.get(
            "/auth/me",
            headers={
                "Authorization": "Bearer synthetic.invalid.jwt",
                "X-API-Key": raw_key,
            },
        )
        _require_fixed(
            response.status_code == 401 and verify_calls[0] == 0,
            "expected an explicitly invalid bearer not to fall through to API-key auth",
        )

    @pytest.mark.asyncio
    async def test_websocket_ticket_bearer_issuance_is_committed_and_uncached(
        self,
        auth_runtime: Any,
    ) -> None:
        from ares.core.campaign import Campaign

        client, database, _, _, token, _ = auth_runtime
        _reset_rate_limiter()
        campaign = Campaign(
            name="Ticket Issuance Campaign",
            operator="separate-owner",
        )
        await database.save_campaign(campaign)
        response = await client.post(
            f"/campaigns/{campaign.id}/websocket-ticket",
            headers=self._bearer_headers(token),
        )
        body = response.json()
        ticket = body.get("ticket") if isinstance(body, dict) else None
        async with database.conn.execute(
            "SELECT COUNT(*) FROM websocket_tickets"
        ) as cursor:
            row_count = int((await cursor.fetchone())[0])
        contract_is_exact = (
            response.status_code == 201
            and set(body) == {"ticket", "expires_in"}
            and isinstance(ticket, str)
            and len(ticket) == 43
            and body.get("expires_in") == 30
            and response.headers.get("cache-control") == "no-store"
            and response.headers.get("pragma") == "no-cache"
            and row_count == 1
        )
        _require_fixed(
            contract_is_exact,
            "expected one committed uncached bearer WebSocket ticket",
        )

    @pytest.mark.parametrize("scope", ["read", "write", "admin"])
    @pytest.mark.asyncio
    async def test_websocket_ticket_api_key_scopes_update_last_used_once(
        self,
        auth_runtime: Any,
        scope: str,
    ) -> None:
        from ares.core.campaign import Campaign

        client, database, user_id, username, _, _ = auth_runtime
        _reset_rate_limiter()
        await database.conn.execute(
            "UPDATE users SET role='operator' WHERE id=?",
            (user_id,),
        )
        campaign = Campaign(
            name="API Key Ticket Campaign",
            operator=username,
        )
        await database.save_campaign(campaign)
        with patch("ares.db.database.logger.info"):
            key_id, raw_key = await database.create_api_key(
                user_id,
                "ticket-key",
                scopes=scope,
            )
        verify_calls = [0]
        original_verify = database.verify_api_key

        async def tracked_verify(candidate: str) -> Any:
            verify_calls[0] += 1
            return await original_verify(candidate)

        database.verify_api_key = tracked_verify  # type: ignore[method-assign]
        response = await client.post(
            f"/campaigns/{campaign.id}/websocket-ticket",
            headers={"X-API-Key": raw_key},
        )
        async with database.conn.execute(
            "SELECT last_used FROM api_keys WHERE id=?",
            (key_id,),
        ) as cursor:
            last_used_present = (await cursor.fetchone())[0] is not None
        async with database.conn.execute(
            "SELECT COUNT(*) FROM websocket_tickets"
        ) as cursor:
            row_count = int((await cursor.fetchone())[0])
        _require_fixed(
            response.status_code == 201
            and verify_calls[0] == 1
            and last_used_present
            and row_count == 1,
            "expected one API-key verification and one committed ticket",
        )

    @pytest.mark.asyncio
    async def test_websocket_ticket_denials_do_not_insert_rows(
        self,
        auth_runtime: Any,
        monkeypatch: Any,
    ) -> None:
        from ares.api import server
        from ares.core.campaign import Campaign

        client, database, user_id, username, token, _ = auth_runtime
        _reset_rate_limiter()
        await database.conn.execute(
            "UPDATE users SET role='operator' WHERE id=?",
            (user_id,),
        )
        inaccessible = Campaign(
            name="Inaccessible Ticket Campaign",
            operator="different-owner",
        )
        accessible = Campaign(
            name="Accessible Ticket Campaign",
            operator=username,
        )
        await database.save_campaign(inaccessible)
        await database.save_campaign(accessible)
        with patch("ares.db.database.logger.info"):
            _, insufficient_key = await database.create_api_key(
                user_id,
                "insufficient-ticket-key",
                scopes="none",
            )

        invalid = await client.post(
            f"/campaigns/{accessible.id}/websocket-ticket",
            headers={"Authorization": "Bearer synthetic.invalid.jwt"},
        )
        insufficient = await client.post(
            f"/campaigns/{accessible.id}/websocket-ticket",
            headers={"X-API-Key": insufficient_key},
        )
        missing = await client.post(
            "/campaigns/missing-ticket-campaign/websocket-ticket",
            headers=self._bearer_headers(token),
        )
        inaccessible_response = await client.post(
            f"/campaigns/{inaccessible.id}/websocket-ticket",
            headers=self._bearer_headers(token),
        )

        original_issue = database.issue_websocket_ticket

        async def lose_authority(_campaign_id: str, _source: Any) -> None:
            return None

        database.issue_websocket_ticket = lose_authority  # type: ignore[method-assign]
        revalidation_loss = await client.post(
            f"/campaigns/{accessible.id}/websocket-ticket",
            headers=self._bearer_headers(token),
        )

        async def fail_issue(_campaign_id: str, _source: Any) -> Any:
            raise RuntimeError

        database.issue_websocket_ticket = fail_issue  # type: ignore[method-assign]
        unavailable = await client.post(
            f"/campaigns/{accessible.id}/websocket-ticket",
            headers=self._bearer_headers(token),
        )
        database.issue_websocket_ticket = original_issue  # type: ignore[method-assign]

        original_limit = server._limiter.is_allowed_async

        async def deny_auth_bucket(key: str, _limit: int) -> tuple[bool, int]:
            return (False, 0) if key.startswith("auth:") else (True, 1)

        monkeypatch.setattr(server._limiter, "is_allowed_async", deny_auth_bucket)
        limited = await client.post(
            f"/campaigns/{accessible.id}/websocket-ticket",
            headers=self._bearer_headers(token),
        )
        monkeypatch.setattr(server._limiter, "is_allowed_async", original_limit)

        async with database.conn.execute(
            "SELECT COUNT(*) FROM websocket_tickets"
        ) as cursor:
            row_count = int((await cursor.fetchone())[0])
        statuses = (
            invalid.status_code,
            insufficient.status_code,
            missing.status_code,
            inaccessible_response.status_code,
            revalidation_loss.status_code,
            limited.status_code,
            unavailable.status_code,
        )
        _require_fixed(
            statuses == (401, 403, 404, 404, 401, 429, 503) and row_count == 0,
            "expected fixed ticket denial statuses without row insertion",
        )


_WS_TEST_DISCONNECT = object()
_WS_TEST_HEARTBEAT = object()


class _FirstBroadcastSendCoordinator:
    """Order-independent barrier for the first of two real send stages."""

    def __init__(self) -> None:
        self._claim_lock = asyncio.Lock()
        self._roles: dict[int, bool] = {}
        self.release_first = asyncio.Event()
        self.first_stalled = asyncio.Event()
        self.first_cancelled = asyncio.Event()
        self.peer_delivered = asyncio.Event()
        self.active_count = 0
        self.settled_count = 0

    async def before_send(self, socket: Any) -> None:
        async with self._claim_lock:
            is_first = not self._roles
            self._roles[id(socket)] = is_first
            self.active_count += 1
        if not is_first:
            return
        self.first_stalled.set()
        try:
            await asyncio.wait_for(self.release_first.wait(), timeout=10.0)
        except asyncio.CancelledError:
            self.first_cancelled.set()
            raise
        except TimeoutError:
            pytest.fail(
                "expected the first broadcast send barrier to be released",
                pytrace=False,
            )

    def after_send(self, socket: Any, *, delivered: bool) -> None:
        is_first = self._roles.pop(id(socket), None)
        if is_first is None:
            return
        self.active_count -= 1
        self.settled_count += 1
        if not is_first and delivered:
            self.peer_delivered.set()


class _MainWebSocketHarness:
    """Minimal ASGI peer for the real registered WebSocket route."""

    def __init__(self, app: Any, query_string: bytes = b"") -> None:
        self.scope = {"app": app, "query_string": query_string}
        self.accepted = asyncio.Event()
        self.closed = asyncio.Event()
        self.disconnect_observed = asyncio.Event()
        self.close_code: int | None = None
        self.close_reason: str | None = None
        self.close_calls = 0
        self.sent_types: list[str] = []
        self.sent = asyncio.Queue[str]()
        self.inbound = asyncio.Queue[Any]()
        self.fail_next_send = False
        self.fail_accept = False
        self.block_next_send = False
        self.send_started = asyncio.Event()
        self.send_release = asyncio.Event()
        self.broadcast_send_coordinator: (
            _FirstBroadcastSendCoordinator | None
        ) = None

    async def accept(self) -> None:
        if self.fail_accept:
            raise RuntimeError
        self.accepted.set()

    async def close(self, *, code: int, reason: str) -> None:
        self.close_calls += 1
        self.close_code = code
        self.close_reason = reason
        self.closed.set()
        await self.inbound.put(_WS_TEST_DISCONNECT)

    async def send_json(self, payload: Any) -> None:
        coordinator = self.broadcast_send_coordinator
        delivered = False
        try:
            if coordinator is not None:
                await coordinator.before_send(self)
            if self.block_next_send:
                self.block_next_send = False
                self.send_started.set()
                await _ws_wait(
                    self.send_release.wait(),
                    "expected protected send barrier release",
                )
            if self.fail_next_send:
                self.fail_next_send = False
                raise RuntimeError
            event_type = payload.get("type") if isinstance(payload, dict) else None
            safe_type = event_type if isinstance(event_type, str) else "unknown"
            self.sent_types.append(safe_type)
            await self.sent.put(safe_type)
            delivered = True
        finally:
            if coordinator is not None:
                coordinator.after_send(self, delivered=delivered)

    async def receive_text(self) -> str:
        item = await self.inbound.get()
        if item is _WS_TEST_HEARTBEAT:
            raise TimeoutError
        if item is _WS_TEST_DISCONNECT:
            self.disconnect_observed.set()
            from starlette.websockets import WebSocketDisconnect

            raise WebSocketDisconnect
        return str(item)

    async def client_disconnect(self) -> None:
        await self.inbound.put(_WS_TEST_DISCONNECT)

    async def trigger_heartbeat(self) -> None:
        await self.inbound.put(_WS_TEST_HEARTBEAT)


async def _ws_wait(awaitable: Any, message: str) -> Any:
    try:
        return await asyncio.wait_for(awaitable, timeout=3.0)
    except TimeoutError:
        pytest.fail(message, pytrace=False)


def _main_campaign_websocket_endpoint(app: Any) -> Any:
    endpoints = [
        getattr(route, "endpoint", None)
        for route in app.routes
        if getattr(route, "path", None) == "/ws/campaigns/{campaign_id}/events"
    ]
    if len(endpoints) != 1 or endpoints[0] is None:
        pytest.fail("expected exactly one main campaign WebSocket route", pytrace=False)
    return endpoints[0]


async def _launch_main_websocket(
    app: Any,
    campaign_id: str,
    *,
    ticket: str | None = None,
    token: str | None = None,
    api_key: str | None = None,
    query_string: bytes | None = None,
    fail_accept: bool = False,
) -> tuple[_MainWebSocketHarness, asyncio.Task[None]]:
    if query_string is None:
        if ticket is None and (token is not None or api_key is not None):
            ticket = await _issue_main_websocket_ticket(
                app,
                campaign_id,
                token=token,
                api_key=api_key,
            )
        query_string = b"" if ticket is None else b"ticket=" + ticket.encode("ascii")
    socket = _MainWebSocketHarness(app, query_string)
    socket.fail_accept = fail_accept
    endpoint = _main_campaign_websocket_endpoint(app)
    task = asyncio.create_task(endpoint(socket, campaign_id))
    return socket, task


async def _request_main_websocket_ticket(
    app: Any,
    campaign_id: str,
    *,
    token: str | None = None,
    api_key: str | None = None,
) -> httpx.Response:
    headers: dict[str, str] = {}
    if token is not None:
        headers["Authorization"] = f"Bearer {token}"
    if api_key is not None:
        headers["X-API-Key"] = api_key
    async with httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app),
        base_url="http://localhost",
    ) as client:
        return await client.post(
            f"/campaigns/{campaign_id}/websocket-ticket",
            headers=headers,
        )


async def _issue_main_websocket_ticket(
    app: Any,
    campaign_id: str,
    *,
    token: str | None = None,
    api_key: str | None = None,
) -> str:
    response = await _request_main_websocket_ticket(
        app,
        campaign_id,
        token=token,
        api_key=api_key,
    )
    body = response.json()
    ticket = body.get("ticket") if isinstance(body, dict) else None
    canonical = (
        response.status_code == 201
        and isinstance(ticket, str)
        and len(ticket) == 43
        and body.get("expires_in") == 30
    )
    _require_fixed(canonical, "expected committed WebSocket ticket issuance")
    return ticket


async def _settle_main_websocket(
    socket: _MainWebSocketHarness,
    task: asyncio.Task[None],
) -> None:
    if not task.done():
        await socket.client_disconnect()
    try:
        await asyncio.wait_for(asyncio.shield(task), timeout=3.0)
    except TimeoutError:
        task.cancel()
        try:
            await task
        except asyncio.CancelledError:
            pass
        pytest.fail("expected main WebSocket task to terminate", pytrace=False)


class TestMainWebSocketAuthoritativeLifetime:
    @pytest.fixture
    async def ws_runtime(
        self,
        tmp_path: Any,
    ) -> Any:
        from ares.api import server
        from ares.core.campaign import Campaign
        from ares.core.security import create_access_token
        from ares.db import database as database_module
        from ares.db.database import AresDatabase

        database = await AresDatabase.create(tmp_path / "main-websocket.db")
        username = "main-websocket-principal"
        with patch.object(database_module.logger, "info"):
            user_id = await database.create_user(
                username,
                "SyntheticWebSocketPass1!",
                "team_lead",
            )
        issued = await database.create_login_session(
            username,
            "SyntheticWebSocketPass1!",
            lambda claims: create_access_token(
                dict(claims),
                _settings().secret_key_value,
                algorithm=_settings().ares_jwt_algorithm,
                expires_minutes=60,
            ),
        )
        _require_fixed(
            issued.session is not None,
            "expected authoritative WebSocket login session",
        )
        token = issued.session.access_token
        campaign = Campaign(
            name="Synthetic WebSocket Campaign",
            operator="separate-campaign-owner",
        )
        await database.save_campaign(campaign)
        original_db = getattr(server.app.state, "db", None)
        original_db_override = server.app.dependency_overrides.get(server.get_db)
        server.app.state.db = database
        server.app.dependency_overrides[server.get_db] = lambda: database
        server._ws_connections.clear()
        _reset_rate_limiter()
        try:
            yield server, database, user_id, username, token, campaign, server.app
        finally:
            if original_db_override is None:
                server.app.dependency_overrides.pop(server.get_db, None)
            else:
                server.app.dependency_overrides[server.get_db] = original_db_override
            server._ws_connections.clear()
            server.app.state.db = original_db
            await database.close()

    @staticmethod
    async def _await_connected(socket: _MainWebSocketHarness) -> None:
        await _ws_wait(
            socket.accepted.wait(),
            "expected main WebSocket handshake acceptance",
        )
        initial_type = await _ws_wait(
            socket.sent.get(),
            "expected main WebSocket connected event",
        )
        _require_fixed(
            initial_type == "connected",
            "expected the fixed connected event after authorization",
        )

    @staticmethod
    async def _await_denied(
        socket: _MainWebSocketHarness,
        task: asyncio.Task[None],
        *,
        code: int,
    ) -> None:
        await _ws_wait(
            socket.closed.wait(),
            "expected main WebSocket handshake denial",
        )
        await _ws_wait(task, "expected denied WebSocket route to terminate")
        safe_contract = (
            not socket.accepted.is_set()
            and socket.close_code == code
            and socket.close_reason
            in {
                "Authentication or authorization failed",
                "Authentication service unavailable",
            }
            and socket.close_calls == 1
        )
        _require_fixed(
            safe_contract,
            "expected fixed WebSocket denial code and reason",
        )

    @pytest.mark.asyncio
    async def test_active_bearer_and_api_key_use_real_authoritative_handshake(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, user_id, _, token, campaign, app = ws_runtime
        bearer_socket, bearer_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        try:
            await self._await_connected(bearer_socket)
            registered = list(server._ws_connections.get(campaign.id, set()))
            representation_safe = (
                len(registered) == 1 and token not in repr(registered[0])
            )
            _require_fixed(
                representation_safe,
                "expected opaque registry state without credential representation",
            )
        finally:
            await _settle_main_websocket(bearer_socket, bearer_task)

        with patch("ares.db.database.logger.info"):
            _, raw_key = await database.create_api_key(
                user_id,
                "main-websocket-read-key",
                scopes="read",
            )
        key_socket, key_task = await _launch_main_websocket(
            app,
            campaign.id,
            api_key=raw_key,
        )
        try:
            await self._await_connected(key_socket)
            key_representation_safe = all(
                raw_key not in repr(connection)
                for connection in server._ws_connections.get(campaign.id, set())
            )
            _require_fixed(
                key_representation_safe,
                "expected API-key connection state to hide the credential",
            )
        finally:
            await _settle_main_websocket(key_socket, key_task)

    @pytest.mark.asyncio
    async def test_ticket_is_single_use_and_concurrent_handshake_has_one_winner(
        self,
        ws_runtime: Any,
    ) -> None:
        _, _, _, _, token, campaign, app = ws_runtime
        ticket = await _issue_main_websocket_ticket(app, campaign.id, token=token)
        first_socket, first_task = await _launch_main_websocket(
            app, campaign.id, ticket=ticket
        )
        second_socket, second_task = await _launch_main_websocket(
            app, campaign.id, ticket=ticket
        )
        try:
            async def wait_for_outcome(socket: _MainWebSocketHarness) -> None:
                accepted = asyncio.create_task(socket.accepted.wait())
                closed = asyncio.create_task(socket.closed.wait())
                done, pending = await asyncio.wait(
                    {accepted, closed},
                    return_when=asyncio.FIRST_COMPLETED,
                )
                for waiter in pending:
                    waiter.cancel()
                await asyncio.gather(*pending, return_exceptions=True)
                _require_fixed(bool(done), "expected a handshake outcome")

            await _ws_wait(
                asyncio.gather(
                    wait_for_outcome(first_socket),
                    wait_for_outcome(second_socket),
                ),
                "expected exactly one concurrent ticket winner",
            )
            accepted_count = sum(
                socket.accepted.is_set() for socket in (first_socket, second_socket)
            )
            denied_count = sum(
                socket.close_code == 4001 for socket in (first_socket, second_socket)
            )
            _require_fixed(
                accepted_count == 1 and denied_count == 1,
                "expected one accepted and one replay-denied handshake",
            )
        finally:
            await _settle_main_websocket(first_socket, first_task)
            await _settle_main_websocket(second_socket, second_task)

        replay_socket, replay_task = await _launch_main_websocket(
            app, campaign.id, ticket=ticket
        )
        await self._await_denied(replay_socket, replay_task, code=4001)

    @pytest.mark.parametrize(
        "query_string",
        [
            b"",
            b"ticket=",
            b"ticket=short",
            b"ticket%3Dsynthetic",
            b"%74icket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
            b"ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%41",
            b"ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&extra=1",
            b"extra=1&ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
            b"ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
            b"token=synthetic-legacy-value",
            b"api_key=synthetic-legacy-value",
            b"ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&token=legacy",
            b"ticket=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA&api_key=legacy",
        ],
    )
    @pytest.mark.asyncio
    async def test_ticket_query_parser_rejects_every_noncanonical_shape_before_db(
        self,
        ws_runtime: Any,
        query_string: bytes,
    ) -> None:
        _, database, _, _, _, campaign, app = ws_runtime
        consume_calls = [0]
        original_consume = database.consume_websocket_ticket

        async def tracked_consume(raw_ticket: str, campaign_id: str) -> Any:
            consume_calls[0] += 1
            return await original_consume(raw_ticket, campaign_id)

        database.consume_websocket_ticket = tracked_consume  # type: ignore[method-assign]
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            query_string=query_string,
        )
        try:
            await self._await_denied(socket, task, code=4001)
            _require_fixed(
                consume_calls[0] == 0 and socket.scope["query_string"] == b"",
                "expected malformed query rejection after synchronous scrubbing",
            )
        finally:
            database.consume_websocket_ticket = original_consume  # type: ignore[method-assign]

    @pytest.mark.asyncio
    async def test_wrong_campaign_does_not_consume_ticket(
        self,
        ws_runtime: Any,
    ) -> None:
        from ares.core.campaign import Campaign

        _, database, _, _, token, campaign, app = ws_runtime
        other_campaign = Campaign(
            name="Wrong Ticket Campaign",
            operator="separate-owner",
        )
        await database.save_campaign(other_campaign)
        ticket = await _issue_main_websocket_ticket(app, campaign.id, token=token)
        wrong_socket, wrong_task = await _launch_main_websocket(
            app, other_campaign.id, ticket=ticket
        )
        await self._await_denied(wrong_socket, wrong_task, code=4001)
        correct_socket, correct_task = await _launch_main_websocket(
            app, campaign.id, ticket=ticket
        )
        try:
            await self._await_connected(correct_socket)
        finally:
            await _settle_main_websocket(correct_socket, correct_task)

    @pytest.mark.asyncio
    async def test_expired_ticket_and_consume_outage_use_fixed_close_codes(
        self,
        ws_runtime: Any,
    ) -> None:
        _, database, _, _, token, campaign, app = ws_runtime
        expired_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        await database.conn.execute(
            "UPDATE websocket_tickets SET created_at=?, expires_at=? "
            "WHERE consumed_at IS NULL",
            (
                "1999-12-31T23:59:30.000Z",
                "2000-01-01T00:00:00.000Z",
            ),
        )
        await database.conn.commit()
        expired_socket, expired_task = await _launch_main_websocket(
            app, campaign.id, ticket=expired_ticket
        )
        await self._await_denied(expired_socket, expired_task, code=4001)

        unavailable_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        original_consume = database.consume_websocket_ticket

        async def fail_consume(_ticket: str, _campaign_id: str) -> Any:
            raise ConnectionError

        database.consume_websocket_ticket = fail_consume  # type: ignore[method-assign]
        try:
            unavailable_socket, unavailable_task = await _launch_main_websocket(
                app, campaign.id, ticket=unavailable_ticket
            )
            await self._await_denied(
                unavailable_socket,
                unavailable_task,
                code=1013,
            )
        finally:
            database.consume_websocket_ticket = original_consume  # type: ignore[method-assign]

    @pytest.mark.asyncio
    async def test_failed_accept_keeps_ticket_consumed_and_fresh_ticket_recovers(
        self,
        ws_runtime: Any,
    ) -> None:
        _, _, _, _, token, campaign, app = ws_runtime
        ticket = await _issue_main_websocket_ticket(app, campaign.id, token=token)
        failed_socket, failed_task = await _launch_main_websocket(
            app, campaign.id, ticket=ticket, fail_accept=True
        )
        failed_accept_observed = False
        try:
            await failed_task
        except RuntimeError:
            failed_accept_observed = True
        _require_fixed(
            failed_accept_observed,
            "expected the synthetic accept failure to propagate",
        )

        replay_socket, replay_task = await _launch_main_websocket(
            app, campaign.id, ticket=ticket
        )
        await self._await_denied(replay_socket, replay_task, code=4001)

        recovered_socket, recovered_task = await _launch_main_websocket(
            app, campaign.id, token=token
        )
        try:
            await self._await_connected(recovered_socket)
        finally:
            await _settle_main_websocket(recovered_socket, recovered_task)

    @pytest.mark.asyncio
    async def test_bearer_handshake_denies_inactive_renamed_revoked_and_deleted(
        self,
        ws_runtime: Any,
    ) -> None:
        _, database, user_id, username, token, campaign, app = ws_runtime

        inactive_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        await database.conn.execute(
            "UPDATE users SET is_active=0 WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        inactive_socket, inactive_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=inactive_ticket,
        )
        await self._await_denied(inactive_socket, inactive_task, code=4001)

        await database.conn.execute(
            "UPDATE users SET is_active=1 WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        renamed_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        await database.conn.execute(
            "UPDATE users SET username=? WHERE id=?",
            ("renamed-main-websocket-principal", user_id),
        )
        await database.conn.commit()
        renamed_socket, renamed_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=renamed_ticket,
        )
        await self._await_denied(renamed_socket, renamed_task, code=4001)

        await database.conn.execute(
            "UPDATE users SET username=? WHERE id=?",
            (username, user_id),
        )
        await database.conn.commit()
        from datetime import datetime, timedelta

        expired_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        await database.conn.execute(
            "UPDATE websocket_tickets SET bearer_expires_at=? "
            "WHERE consumed_at IS NULL",
            ("2000-01-01T00:00:00.000Z",),
        )
        await database.conn.commit()
        expired_socket, expired_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=expired_ticket,
        )
        await self._await_denied(expired_socket, expired_task, code=4001)

        import jwt

        settings = _settings()
        authoritative_claims = jwt.decode(
            token,
            settings.secret_key_value,
            algorithms=[settings.ares_jwt_algorithm],
        )
        revocation_marker = "synthetic-main-websocket-revocation"
        revoked_token = jwt.encode(
            {
                "sub": username,
                "sid": authoritative_claims["sid"],
                "ver": authoritative_claims["ver"],
                "jti": revocation_marker,
                "exp": datetime.now(UTC) + timedelta(hours=1),
            },
            settings.secret_key_value,
            algorithm=settings.ares_jwt_algorithm,
        )
        revoked_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=revoked_token
        )
        await database.revoke_access_token(
            revocation_marker,
            user_id,
            (datetime.now(UTC) + timedelta(hours=1)).isoformat(),
        )
        revoked_socket, revoked_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=revoked_ticket,
        )
        await self._await_denied(revoked_socket, revoked_task, code=4001)

        deleted_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        await database.conn.execute("DELETE FROM users WHERE id=?", (user_id,))
        await database.conn.commit()
        deleted_socket, deleted_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=deleted_ticket,
        )
        await self._await_denied(deleted_socket, deleted_task, code=4001)

    @pytest.mark.asyncio
    async def test_current_role_and_campaign_ownership_control_handshake(
        self,
        ws_runtime: Any,
    ) -> None:
        _, database, user_id, _, token, campaign, app = ws_runtime
        ticket = await _issue_main_websocket_ticket(app, campaign.id, token=token)
        await database.conn.execute(
            "UPDATE users SET role='operator' WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=ticket,
        )
        await self._await_denied(socket, task, code=4001)

    @pytest.mark.asyncio
    async def test_explicit_invalid_bearer_is_terminal_over_valid_api_key(
        self,
        ws_runtime: Any,
    ) -> None:
        _, database, user_id, _, _, campaign, app = ws_runtime
        missing_socket, missing_task = await _launch_main_websocket(
            app,
            campaign.id,
        )
        await self._await_denied(missing_socket, missing_task, code=4001)

        with patch("ares.db.database.logger.info"):
            _, raw_key = await database.create_api_key(
                user_id,
                "main-websocket-precedence-key",
            )
        verify_calls = [0]
        original_verify = database.verify_api_key

        async def tracked_verify(candidate: str) -> Any:
            verify_calls[0] += 1
            return await original_verify(candidate)

        database.verify_api_key = tracked_verify  # type: ignore[method-assign]
        response = await _request_main_websocket_ticket(
            app,
            campaign.id,
            token="synthetic.invalid.jwt",
            api_key=raw_key,
        )
        database.verify_api_key = original_verify  # type: ignore[method-assign]
        _require_fixed(
            response.status_code == 401 and verify_calls[0] == 0,
            "expected bearer issuance failure to remain terminal",
        )

        legacy_socket, legacy_task = await _launch_main_websocket(
            app,
            campaign.id,
            query_string=b"api_key=synthetic-legacy-value",
        )
        await self._await_denied(legacy_socket, legacy_task, code=4001)

    @pytest.mark.asyncio
    async def test_api_key_revocation_and_inactive_owner_deny_handshake(
        self,
        ws_runtime: Any,
    ) -> None:
        _, database, user_id, _, _, campaign, app = ws_runtime
        with patch("ares.db.database.logger.info"):
            key_id, raw_key = await database.create_api_key(
                user_id,
                "main-websocket-lifecycle-key",
            )
        revoked_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, api_key=raw_key
        )
        await database.conn.execute(
            "UPDATE api_keys SET is_active=0 WHERE id=?",
            (key_id,),
        )
        await database.conn.commit()
        revoked_socket, revoked_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=revoked_ticket,
        )
        await self._await_denied(revoked_socket, revoked_task, code=4001)

        await database.conn.execute(
            "UPDATE api_keys SET is_active=1 WHERE id=?",
            (key_id,),
        )
        await database.conn.commit()
        inactive_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, api_key=raw_key
        )
        await database.conn.execute(
            "UPDATE users SET is_active=0 WHERE id=?",
            (user_id,),
        )
        await database.conn.commit()
        inactive_socket, inactive_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=inactive_ticket,
        )
        await self._await_denied(inactive_socket, inactive_task, code=4001)

    @pytest.mark.asyncio
    async def test_absent_closed_and_failing_backend_close_1013_then_recover(
        self,
        ws_runtime: Any,
    ) -> None:
        _, database, _, _, token, campaign, app = ws_runtime
        absent_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        app.state.db = None
        absent_socket, absent_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=absent_ticket,
        )
        await self._await_denied(absent_socket, absent_task, code=1013)

        app.state.db = database
        closed_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        await database.close()
        closed_socket, closed_task = await _launch_main_websocket(
            app,
            campaign.id,
            ticket=closed_ticket,
        )
        await self._await_denied(closed_socket, closed_task, code=1013)
        await database.connect()

        failed_ticket = await _issue_main_websocket_ticket(
            app, campaign.id, token=token
        )
        original_resolve = database.resolve_websocket_ticket_principal

        async def fail_lookup(_handle: Any) -> Any:
            raise TimeoutError

        database.resolve_websocket_ticket_principal = fail_lookup  # type: ignore[method-assign]
        try:
            failed_socket, failed_task = await _launch_main_websocket(
                app,
                campaign.id,
                ticket=failed_ticket,
            )
            await self._await_denied(failed_socket, failed_task, code=1013)
        finally:
            database.resolve_websocket_ticket_principal = original_resolve  # type: ignore[method-assign]

        recovered_socket, recovered_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        try:
            await self._await_connected(recovered_socket)
        finally:
            await _settle_main_websocket(recovered_socket, recovered_task)

    @pytest.mark.parametrize(
        "state_change",
        ["inactive", "renamed", "deleted", "revoked", "expired", "demoted"],
    )
    @pytest.mark.asyncio
    async def test_bearer_lifetime_revalidation_closes_before_event(
        self,
        ws_runtime: Any,
        state_change: str,
    ) -> None:
        server, database, user_id, username, token, campaign, app = ws_runtime
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        try:
            await self._await_connected(socket)
            if state_change == "inactive":
                await database.conn.execute(
                    "UPDATE users SET is_active=0 WHERE id=?",
                    (user_id,),
                )
                await database.conn.commit()
            elif state_change == "renamed":
                await database.conn.execute(
                    "UPDATE users SET username=? WHERE id=?",
                    ("renamed-after-websocket-connect", user_id),
                )
                await database.conn.commit()
            elif state_change == "deleted":
                await database.conn.execute(
                    "DELETE FROM users WHERE id=?",
                    (user_id,),
                )
                await database.conn.commit()
            elif state_change == "revoked":
                from datetime import datetime, timedelta

                from ares.core.security import decode_access_token

                settings = _settings()
                payload = decode_access_token(
                    token,
                    settings.secret_key_value,
                    settings.ares_jwt_algorithm,
                )
                revocation_marker = payload.get("jti") if payload else None
                if not isinstance(revocation_marker, str):
                    pytest.fail(
                        "expected generated bearer to contain a revocation marker",
                        pytrace=False,
                    )
                await database.revoke_access_token(
                    revocation_marker,
                    user_id,
                    (datetime.now(UTC) + timedelta(hours=1)).isoformat(),
                )
            elif state_change == "expired":
                contexts = list(server._ws_connections.get(campaign.id, set()))
                _require_fixed(
                    len(contexts) == 1,
                    "expected one registered ticket handle",
                )
                await database.conn.execute(
                    "UPDATE refresh_token_families SET created_at='1999-01-01T00:00:00.000Z', "
                    "absolute_expires_at='2000-01-01T00:00:00.000Z', retain_until='2000-01-02T00:00:00.000Z' "
                    "WHERE id=?",
                    (contexts[0].ticket_handle.bearer_family_id,),
                )
                await database.conn.commit()
            else:
                await database.conn.execute(
                    "UPDATE users SET role='operator' WHERE id=?",
                    (user_id,),
                )
                await database.conn.commit()

            await server._broadcast_event(
                campaign.id,
                {"type": "synthetic_protected_event"},
            )
            await _ws_wait(
                socket.closed.wait(),
                "expected stale bearer connection to close before delivery",
            )
            no_protected_event = (
                socket.close_code == 4001
                and socket.close_reason == "Authentication or authorization failed"
                and socket.sent_types == ["connected"]
                and not server._ws_connections.get(campaign.id)
            )
            _require_fixed(
                no_protected_event,
                "expected bearer state change to prevent protected delivery",
            )
        finally:
            await _settle_main_websocket(socket, task)

    @pytest.mark.parametrize(
        "state_change",
        ["revoked", "inactive", "ownership", "scope", "expired", "key_owner"],
    )
    @pytest.mark.asyncio
    async def test_api_key_and_ownership_lifetime_revalidation(
        self,
        ws_runtime: Any,
        state_change: str,
    ) -> None:
        server, database, user_id, username, _, campaign, app = ws_runtime
        await database.conn.execute(
            "UPDATE users SET role='operator' WHERE id=?",
            (user_id,),
        )
        await database.conn.execute(
            "UPDATE campaigns SET operator=? WHERE id=?",
            (username, campaign.id),
        )
        await database.conn.commit()
        with patch("ares.db.database.logger.info"):
            key_id, raw_key = await database.create_api_key(
                user_id,
                "main-websocket-revalidation-key",
            )
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            api_key=raw_key,
        )
        try:
            await self._await_connected(socket)
            if state_change == "revoked":
                await database.conn.execute(
                    "UPDATE api_keys SET is_active=0 WHERE id=?",
                    (key_id,),
                )
            elif state_change == "inactive":
                await database.conn.execute(
                    "UPDATE users SET is_active=0 WHERE id=?",
                    (user_id,),
                )
            elif state_change == "ownership":
                await database.conn.execute(
                    "UPDATE campaigns SET operator=? WHERE id=?",
                    ("different-campaign-owner", campaign.id),
                )
            elif state_change == "scope":
                await database.conn.execute(
                    "UPDATE api_keys SET scopes='none' WHERE id=?",
                    (key_id,),
                )
            elif state_change == "expired":
                await database.conn.execute(
                    "UPDATE api_keys SET expires_at=? WHERE id=?",
                    ("2000-01-01T00:00:00+00:00", key_id),
                )
            else:
                with patch("ares.db.database.logger.info"):
                    replacement_user_id = await database.create_user(
                        "main-websocket-key-owner",
                        "SyntheticKeyOwnerPass1!",
                        "team_lead",
                    )
                await database.conn.execute(
                    "UPDATE api_keys SET user_id=? WHERE id=?",
                    (replacement_user_id, key_id),
                )
            await database.conn.commit()

            await server._broadcast_event(
                campaign.id,
                {"type": "synthetic_protected_event"},
            )
            await _ws_wait(
                socket.closed.wait(),
                "expected stale API-key or ownership connection to close",
            )
            denied_without_delivery = (
                socket.close_code == 4001
                and socket.sent_types == ["connected"]
                and not server._ws_connections.get(campaign.id)
            )
            _require_fixed(
                denied_without_delivery,
                "expected API-key or ownership change to prevent delivery",
            )
        finally:
            await _settle_main_websocket(socket, task)

    @pytest.mark.asyncio
    async def test_heartbeat_revalidates_without_broadcast(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, user_id, _, token, campaign, app = ws_runtime
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        try:
            await self._await_connected(socket)
            await database.conn.execute(
                "UPDATE users SET is_active=0 WHERE id=?",
                (user_id,),
            )
            await database.conn.commit()
            await socket.trigger_heartbeat()
            await _ws_wait(
                socket.closed.wait(),
                "expected heartbeat to detect authorization loss",
            )
            heartbeat_denied = (
                socket.close_code == 4001
                and socket.sent_types == ["connected"]
                and not server._ws_connections.get(campaign.id)
            )
            _require_fixed(
                heartbeat_denied,
                "expected heartbeat revalidation before keepalive delivery",
            )
        finally:
            await _settle_main_websocket(socket, task)

    @pytest.mark.asyncio
    async def test_pong_revalidates_without_broadcast(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, user_id, _, token, campaign, app = ws_runtime
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        try:
            await self._await_connected(socket)
            await database.conn.execute(
                "UPDATE users SET is_active=0 WHERE id=?",
                (user_id,),
            )
            await database.conn.commit()
            await socket.inbound.put("ping")
            await _ws_wait(
                socket.closed.wait(),
                "expected pong authorization loss to close the connection",
            )
            _require_fixed(
                socket.close_code == 4001
                and socket.sent_types == ["connected"]
                and not server._ws_connections.get(campaign.id),
                "expected principal revalidation before pong delivery",
            )
        finally:
            await _settle_main_websocket(socket, task)

    @pytest.mark.asyncio
    async def test_consumed_handle_survives_ticket_expiry_and_purge_read_only(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, user_id, username, _, campaign, app = ws_runtime
        await database.conn.execute(
            "UPDATE users SET role='operator' WHERE id=?",
            (user_id,),
        )
        await database.conn.execute(
            "UPDATE campaigns SET operator=? WHERE id=?",
            (username, campaign.id),
        )
        await database.conn.commit()
        with patch("ares.db.database.logger.info"):
            key_id, raw_key = await database.create_api_key(
                user_id,
                "read-only-lifetime-key",
                scopes="read",
            )
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            api_key=raw_key,
        )
        try:
            await self._await_connected(socket)
            async with database.conn.execute(
                "SELECT last_used FROM api_keys WHERE id=?",
                (key_id,),
            ) as cursor:
                last_used_before = (await cursor.fetchone())[0]
            await database.conn.execute(
                "UPDATE websocket_tickets "
                "SET created_at=?, consumed_at=?, expires_at=?",
                (
                    "1999-12-31T23:59:00.000Z",
                    "1999-12-31T23:59:15.000Z",
                    "1999-12-31T23:59:30.000Z",
                ),
            )
            await database.conn.commit()
            await database.purge_expired_websocket_tickets()
            await server._broadcast_event(
                campaign.id,
                {"type": "module_complete"},
            )
            await server._broadcast_event(
                campaign.id,
                {"type": "strategy_update"},
            )
            first = await _ws_wait(
                socket.sent.get(),
                "expected module event after ticket purge",
            )
            second = await _ws_wait(
                socket.sent.get(),
                "expected strategy event after ticket purge",
            )
            async with database.conn.execute(
                "SELECT last_used FROM api_keys WHERE id=?",
                (key_id,),
            ) as cursor:
                last_used_after = (await cursor.fetchone())[0]
            async with database.conn.execute(
                "SELECT COUNT(*) FROM websocket_tickets"
            ) as cursor:
                ticket_rows = int((await cursor.fetchone())[0])
            _require_fixed(
                (first, second) == ("module_complete", "strategy_update")
                and ticket_rows == 0
                and last_used_before == last_used_after,
                "expected purged handle authority with read-only API-key resolution",
            )
        finally:
            await _settle_main_websocket(socket, task)

    @pytest.mark.asyncio
    async def test_delayed_authoritative_lookup_observes_committed_invalidation(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, user_id, _, token, campaign, app = ws_runtime
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        lookup_started = asyncio.Event()
        lookup_release = asyncio.Event()
        original_resolve = database.resolve_websocket_ticket_principal

        async def delayed_resolve(handle: Any) -> Any:
            lookup_started.set()
            await _ws_wait(
                lookup_release.wait(),
                "expected authoritative lookup barrier release",
            )
            return await original_resolve(handle)

        try:
            await self._await_connected(socket)
            database.resolve_websocket_ticket_principal = delayed_resolve  # type: ignore[method-assign]
            broadcast_task = asyncio.create_task(
                server._broadcast_event(
                    campaign.id,
                    {"type": "synthetic_protected_event"},
                )
            )
            await _ws_wait(
                lookup_started.wait(),
                "expected authoritative lookup barrier to be reached",
            )
            await database.conn.execute(
                "UPDATE users SET is_active=0 WHERE id=?",
                (user_id,),
            )
            await database.conn.commit()
            lookup_release.set()
            await _ws_wait(
                broadcast_task,
                "expected delayed protected broadcast to terminate",
            )
            await _ws_wait(
                socket.closed.wait(),
                "expected committed invalidation to close delayed connection",
            )
            _require_fixed(
                socket.sent_types == ["connected"]
                and socket.close_code == 4001
                and not server._ws_connections.get(campaign.id),
                "expected post-barrier authoritative state to prevent delivery",
            )
        finally:
            lookup_release.set()
            database.resolve_websocket_ticket_principal = original_resolve  # type: ignore[method-assign]
            await _settle_main_websocket(socket, task)

    @pytest.mark.asyncio
    async def test_backend_failure_after_connect_closes_1013_and_new_connection_recovers(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, _, _, token, campaign, app = ws_runtime
        socket, task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        original_resolve = database.resolve_websocket_ticket_principal

        async def fail_lookup(_handle: Any) -> Any:
            raise ConnectionError

        try:
            await self._await_connected(socket)
            database.resolve_websocket_ticket_principal = fail_lookup  # type: ignore[method-assign]
            await server._broadcast_event(
                campaign.id,
                {"type": "synthetic_protected_event"},
            )
            await _ws_wait(
                socket.closed.wait(),
                "expected backend failure to close established connection",
            )
            unavailable_without_delivery = (
                socket.close_code == 1013
                and socket.close_reason == "Authentication service unavailable"
                and socket.sent_types == ["connected"]
                and not server._ws_connections.get(campaign.id)
            )
            _require_fixed(
                unavailable_without_delivery,
                "expected backend outage to prevent protected delivery with 1013",
            )
        finally:
            database.resolve_websocket_ticket_principal = original_resolve  # type: ignore[method-assign]
            await _settle_main_websocket(socket, task)

        recovered_socket, recovered_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        try:
            await self._await_connected(recovered_socket)
        finally:
            await _settle_main_websocket(recovered_socket, recovered_task)

    @pytest.mark.asyncio
    async def test_one_failed_connection_does_not_block_an_authorized_peer(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, _, _, token, campaign, app = ws_runtime
        from ares.core.security import create_access_token
        from ares.db import database as database_module

        with patch.object(database_module.logger, "info"):
            await database.create_user(
                "main-websocket-peer",
                "SyntheticWebSocketPeer1!",
                "team_lead",
            )
        peer_session = await database.create_login_session(
            "main-websocket-peer",
            "SyntheticWebSocketPeer1!",
            lambda claims: create_access_token(
                dict(claims),
                _settings().secret_key_value,
                algorithm=_settings().ares_jwt_algorithm,
                expires_minutes=60,
            ),
        )
        _require_fixed(
            peer_session.session is not None,
            "expected authoritative peer session",
        )
        peer_token = peer_session.session.access_token
        first_socket, first_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        second_socket, second_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=peer_token,
        )
        try:
            await self._await_connected(first_socket)
            await self._await_connected(second_socket)
            first_socket.fail_next_send = True
            await server._broadcast_event(
                campaign.id,
                {"type": "synthetic_protected_event"},
            )
            delivered_type = await _ws_wait(
                second_socket.sent.get(),
                "expected authorized peer delivery after another send failure",
            )
            delivery_isolated = (
                delivered_type == "synthetic_protected_event"
                and first_socket.sent_types == ["connected"]
                and len(server._ws_connections.get(campaign.id, set())) == 1
            )
            _require_fixed(
                delivery_isolated,
                "expected one failed connection not to block an authorized peer",
            )
        finally:
            await _settle_main_websocket(first_socket, first_task)
            await _settle_main_websocket(second_socket, second_task)

    @pytest.mark.asyncio
    async def test_authorization_loser_does_not_block_an_authorized_peer(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, user_id, _, token, campaign, app = ws_runtime
        from ares.core.security import create_access_token
        from ares.db import database as database_module

        with patch.object(database_module.logger, "info"):
            await database.create_user(
                "main-websocket-authorized-peer",
                "SyntheticAuthorizedPeerPass1!",
                "team_lead",
            )
        peer_session = await database.create_login_session(
            "main-websocket-authorized-peer",
            "SyntheticAuthorizedPeerPass1!",
            lambda claims: create_access_token(
                dict(claims),
                _settings().secret_key_value,
                algorithm=_settings().ares_jwt_algorithm,
                expires_minutes=60,
            ),
        )
        _require_fixed(
            peer_session.session is not None,
            "expected authoritative peer session",
        )
        peer_token = peer_session.session.access_token
        stale_socket, stale_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        peer_socket, peer_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=peer_token,
        )
        try:
            await self._await_connected(stale_socket)
            await self._await_connected(peer_socket)
            await database.conn.execute(
                "UPDATE users SET is_active=0 WHERE id=?",
                (user_id,),
            )
            await database.conn.commit()
            await server._broadcast_event(
                campaign.id,
                {"type": "synthetic_protected_event"},
            )
            await _ws_wait(
                stale_socket.closed.wait(),
                "expected authorization loser to be retired",
            )
            peer_event_type = await _ws_wait(
                peer_socket.sent.get(),
                "expected authorized peer to receive protected event",
            )
            isolated_delivery = (
                stale_socket.close_code == 4001
                and stale_socket.sent_types == ["connected"]
                and peer_event_type == "synthetic_protected_event"
                and len(server._ws_connections.get(campaign.id, set())) == 1
            )
            _require_fixed(
                isolated_delivery,
                "expected an authorization loser not to block an authorized peer",
            )
        finally:
            await _settle_main_websocket(stale_socket, stale_task)
            await _settle_main_websocket(peer_socket, peer_task)

    @pytest.mark.asyncio
    async def test_slow_first_peer_does_not_delay_authorized_peer(
        self,
        ws_runtime: Any,
    ) -> None:
        server, _, _, _, token, campaign, app = ws_runtime
        first_socket, first_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        second_socket, second_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        coordinator = _FirstBroadcastSendCoordinator()
        broadcast_task: asyncio.Task[None] | None = None
        try:
            await self._await_connected(first_socket)
            await self._await_connected(second_socket)
            first_socket.broadcast_send_coordinator = coordinator
            second_socket.broadcast_send_coordinator = coordinator
            broadcast_task = asyncio.create_task(
                server._broadcast_event(
                    campaign.id,
                    {"type": "synthetic_protected_event"},
                )
            )
            await _ws_wait(
                coordinator.first_stalled.wait(),
                "expected the first protected send to reach the barrier",
            )
            await _ws_wait(
                coordinator.peer_delivered.wait(),
                "expected an authorized peer to receive before slow-peer release",
            )
            delivered_while_first_stalled = (
                not coordinator.release_first.is_set()
                and not broadcast_task.done()
                and sum(
                    socket.sent_types.count("synthetic_protected_event")
                    for socket in (first_socket, second_socket)
                )
                == 1
            )
            _require_fixed(
                delivered_while_first_stalled,
                "expected slow-peer isolation before releasing the first send",
            )

            coordinator.release_first.set()
            await _ws_wait(
                broadcast_task,
                "expected concurrent protected broadcast to complete",
            )
            all_operations_settled = (
                coordinator.active_count == 0
                and coordinator.settled_count == 2
                and all(
                    socket.sent_types
                    == ["connected", "synthetic_protected_event"]
                    for socket in (first_socket, second_socket)
                )
                and len(server._ws_connections.get(campaign.id, set())) == 2
            )
            _require_fixed(
                all_operations_settled,
                "expected both concurrent protected sends to settle",
            )
        finally:
            coordinator.release_first.set()
            first_socket.broadcast_send_coordinator = None
            second_socket.broadcast_send_coordinator = None
            if broadcast_task is not None and not broadcast_task.done():
                await _ws_wait(
                    broadcast_task,
                    "expected slow-peer broadcast cleanup",
                )
            await _settle_main_websocket(first_socket, first_task)
            await _settle_main_websocket(second_socket, second_task)

    @pytest.mark.asyncio
    async def test_cancelled_broadcast_awaits_owned_children(
        self,
        ws_runtime: Any,
    ) -> None:
        server, _, _, _, token, campaign, app = ws_runtime
        first_socket, first_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        second_socket, second_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        coordinator = _FirstBroadcastSendCoordinator()
        broadcast_task: asyncio.Task[None] | None = None
        cancellation_propagated = False
        try:
            await self._await_connected(first_socket)
            await self._await_connected(second_socket)
            first_socket.broadcast_send_coordinator = coordinator
            second_socket.broadcast_send_coordinator = coordinator
            broadcast_task = asyncio.create_task(
                server._broadcast_event(
                    campaign.id,
                    {"type": "synthetic_protected_event"},
                )
            )
            await _ws_wait(
                coordinator.first_stalled.wait(),
                "expected one owned broadcast child to reach the barrier",
            )
            await _ws_wait(
                coordinator.peer_delivered.wait(),
                "expected the unblocked owned child to deliver",
            )
            broadcast_task.cancel()
            try:
                await asyncio.wait_for(broadcast_task, timeout=3.0)
            except asyncio.CancelledError:
                cancellation_propagated = True
            except TimeoutError:
                pytest.fail(
                    "expected parent cancellation to settle owned children",
                    pytrace=False,
                )

            await _ws_wait(
                coordinator.first_cancelled.wait(),
                "expected held child to receive parent cancellation",
            )
            contexts = list(server._ws_connections.get(campaign.id, set()))
            owned_cleanup_complete = (
                cancellation_propagated
                and broadcast_task.done()
                and broadcast_task.cancelled()
                and coordinator.active_count == 0
                and coordinator.settled_count == 2
                and len(contexts) == 2
                and all(not connection.send_lock.locked() for connection in contexts)
            )
            _require_fixed(
                owned_cleanup_complete,
                "expected cancelled broadcast to await every owned child",
            )
        finally:
            coordinator.release_first.set()
            first_socket.broadcast_send_coordinator = None
            second_socket.broadcast_send_coordinator = None
            if broadcast_task is not None and not broadcast_task.done():
                broadcast_task.cancel()
                try:
                    await asyncio.wait_for(broadcast_task, timeout=3.0)
                except asyncio.CancelledError:
                    pass
                except TimeoutError:
                    pytest.fail(
                        "expected cancelled broadcast cleanup",
                        pytrace=False,
                    )
            await _settle_main_websocket(first_socket, first_task)
            await _settle_main_websocket(second_socket, second_task)

    @pytest.mark.asyncio
    async def test_campaign_registry_prevents_cross_campaign_delivery(
        self,
        ws_runtime: Any,
    ) -> None:
        server, database, _, _, token, campaign, app = ws_runtime
        from ares.core.campaign import Campaign

        other_campaign = Campaign(
            name="Synthetic Other WebSocket Campaign",
            operator="separate-campaign-owner",
        )
        await database.save_campaign(other_campaign)
        first_socket, first_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        other_socket, other_task = await _launch_main_websocket(
            app,
            other_campaign.id,
            token=token,
        )
        try:
            await self._await_connected(first_socket)
            await self._await_connected(other_socket)
            await server._broadcast_event(
                campaign.id,
                {"type": "synthetic_protected_event"},
            )
            delivered_type = await _ws_wait(
                first_socket.sent.get(),
                "expected same-campaign protected delivery",
            )
            isolated = (
                delivered_type == "synthetic_protected_event"
                and other_socket.sent.empty()
                and other_socket.sent_types == ["connected"]
            )
            _require_fixed(
                isolated,
                "expected no cross-campaign WebSocket delivery",
            )
        finally:
            await _settle_main_websocket(first_socket, first_task)
            await _settle_main_websocket(other_socket, other_task)

    @pytest.mark.asyncio
    async def test_broadcast_and_disconnect_are_serialized_without_orphan(
        self,
        ws_runtime: Any,
    ) -> None:
        server, _, _, _, token, campaign, app = ws_runtime
        socket, route_task = await _launch_main_websocket(
            app,
            campaign.id,
            token=token,
        )
        broadcast_task: asyncio.Task[None] | None = None
        try:
            await self._await_connected(socket)
            socket.block_next_send = True
            broadcast_task = asyncio.create_task(
                server._broadcast_event(
                    campaign.id,
                    {"type": "synthetic_protected_event"},
                )
            )
            await _ws_wait(
                socket.send_started.wait(),
                "expected protected send barrier to be reached",
            )
            await socket.client_disconnect()
            await _ws_wait(
                socket.disconnect_observed.wait(),
                "expected route to observe client disconnect",
            )
            route_waits_for_send = not route_task.done()
            socket.send_release.set()
            await _ws_wait(
                broadcast_task,
                "expected serialized broadcast to complete",
            )
            await _ws_wait(
                route_task,
                "expected serialized disconnect cleanup to complete",
            )
            serialized_cleanup = (
                route_waits_for_send
                and socket.sent_types
                == ["connected", "synthetic_protected_event"]
                and not server._ws_connections.get(campaign.id)
                and not broadcast_task.cancelled()
                and not route_task.cancelled()
            )
            _require_fixed(
                serialized_cleanup,
                "expected one serialized send and deterministic disconnect cleanup",
            )
        finally:
            socket.send_release.set()
            if broadcast_task is not None and not broadcast_task.done():
                await _ws_wait(
                    broadcast_task,
                    "expected pending broadcast cleanup",
                )
            await _settle_main_websocket(socket, route_task)


@pytest.mark.asyncio
async def test_strategy_active_returns_llm_backends_resiliently():
    """Verify /strategy/active provides fail-safe llm_backends availability without 500s."""
    from starlette.testclient import TestClient

    from ares.api.rbac import AuthenticatedUser, get_current_user
    from ares.api.server import app

    app.dependency_overrides[get_current_user] = lambda: AuthenticatedUser(username="test_op", role="operator")
    try:
        client = TestClient(app, base_url="http://localhost")
        resp = client.get("/strategy/active")
        assert resp.status_code == 200
        data = resp.json()
        assert "llm_backends" in data
        assert isinstance(data["llm_backends"], dict)
        assert "claude" in data["llm_backends"]
        assert "openai" in data["llm_backends"]
        assert "local" in data["llm_backends"]
        assert isinstance(data["llm_backends"]["local"], bool)
    finally:
        app.dependency_overrides.pop(get_current_user, None)