Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(ws8): wire ITSM webhook inbox + ship 113 tests for bidirectional ITSM

Beenu Arora9ff8186d34f8
diff --git a/services/api/app/api/v1/endpoints/inbox.py b/services/api/app/api/v1/endpoints/inbox.py
index e12df7bfa..65d6641d7 100644
--- a/services/api/app/api/v1/endpoints/inbox.py
+++ b/services/api/app/api/v1/endpoints/inbox.py
@@ -74,6 +74,12 @@ ALLOWED_TEMPLATE_IDS: tuple[str, ...] = (
"cef-syslog",
"splunk-hec",
"email-forwarded",
+ # Bidirectional ITSM (Workstream 8) — inbound Jira / ServiceNow webhooks.
+ # Tokens minted with this template terminate at
+ # /api/v1/inbox/itsm/{tenant_token}/{connector_instance_id} on services/api
+ # rather than the generic ingest path, because they need to resolve back
+ # to a specific connector instance and mirror status onto aisoc_cases.
+ "itsm-inbound",
)
# Same character set as connector_type — tightens HMAC body shape.
@@ -96,8 +102,39 @@ def _fingerprint(token: str) -> str:
return f"...{token[-8:]}" if len(token) > 8 else "...<short>"
-def _build_inbox_url(token: str) -> str:
- """Build the absolute inbox URL the customer pastes into the vendor."""
+def _build_inbox_url(token: str, template_id: str | None = None) -> str:
+ """Build the absolute inbox URL the customer pastes into the vendor.
+
+ For most templates (PagerDuty, generic-json, syslog, etc.) the URL
+ terminates at services/ingest, which resolves the token to a tenant
+ + template_id and runs the OCSF normalizer.
+
+ The exception is ``itsm-inbound`` (Workstream 8). Those URLs need to
+ terminate at services/api because they:
+
+ 1. Need a database transaction to update aisoc_cases / case_external_refs.
+ 2. Need to look up case_fanout's earlier outbound projection to find
+ the AiSOC case ID, which lives in the api-service-managed schema.
+ 3. Are pinned to a specific connector instance, so the URL carries a
+ ``{connector_instance_id}`` placeholder that the operator fills in
+ when they paste it into Jira/ServiceNow's webhook config.
+
+ The placeholder ``<connector_instance_id>`` (UUID) is intentionally
+ angle-bracketed so it's obvious in the wizard UI that the operator
+ has to substitute it before saving the URL on the vendor side.
+ """
+ if template_id == "itsm-inbound":
+ # Public URL of the API service (NOT the ingest service). Reuses
+ # ``OAUTH_PUBLIC_BASE_URL`` because that's already the canonical
+ # "where does the world reach my API" setting — adding a separate
+ # ``API_PUBLIC_URL`` would duplicate the same value with different
+ # names. Falls back to a relative path when unset, which is fine
+ # for dev / docker-compose where the operator paste happens on the
+ # same host the API is exposed from.
+ api_base = (getattr(settings, "OAUTH_PUBLIC_BASE_URL", "") or "").rstrip("/")
+ path = f"/api/v1/inbox/itsm/{token}/<connector_instance_id>"
+ return f"{api_base}{path}" if api_base else path
+
base = (getattr(settings, "INGEST_PUBLIC_URL", "") or "").rstrip("/")
return f"{base}/v1/inbox/{token}" if base else f"/v1/inbox/{token}"
@@ -239,6 +276,17 @@ _TEMPLATE_CATALOG: dict[str, dict[str, str]] = {
),
"category": "email",
},
+ "itsm-inbound": {
+ "label": "Inbound ITSM (Jira / ServiceNow)",
+ "description": (
+ "Receive status-change webhooks from Jira or ServiceNow. The URL "
+ "must be paired with a specific connector instance — paste it "
+ "into the vendor's webhook config alongside the connector ID. "
+ "Tokens of this type terminate at services/api so we can mirror "
+ "status onto aisoc_cases."
+ ),
+ "category": "itsm",
+ },
}
@@ -253,7 +301,7 @@ def _to_response(row: TenantInboxToken, *, include_plaintext: bool) -> InboxToke
"""
return InboxTokenResponse(
token=row.token if include_plaintext else _fingerprint(row.token),
- inbox_url=_build_inbox_url(row.token),
+ inbox_url=_build_inbox_url(row.token, row.template_id),
template_id=row.template_id,
label=row.label,
has_hmac_secret=row.hmac_secret is not None,
diff --git a/services/api/app/api/v1/endpoints/inbox_itsm.py b/services/api/app/api/v1/endpoints/inbox_itsm.py
new file mode 100644
index 000000000..1ca853d84
--- /dev/null
+++ b/services/api/app/api/v1/endpoints/inbox_itsm.py
@@ -0,0 +1,824 @@
+"""Inbound ITSM webhook receiver — Workstream 8 (bidirectional ITSM).
+
+Public-facing counterpart to the *outbound* fan-out implemented in
+``app.services.case_fanout``. The flow it closes is:
+
+1. AiSOC case is created or its status changes →
+2. ``case_fanout`` POSTs to ``services/connectors`` →
+3. Connector creates / updates a Jira issue or ServiceNow incident →
+4. Operator works the ticket *in their existing ITSM*, eventually
+ transitioning it to "In Progress" / "Done" / "Resolved" / "Closed".
+5. Their ITSM fires a webhook at THIS endpoint →
+6. We resolve the inbound ticket back to its AiSOC case via
+ ``case_external_refs`` and mirror the status onto ``aisoc_cases``.
+
+This is what makes ITSM "the source of truth" — operators never have
+to log into AiSOC to change a ticket status; the ITSM they already
+live in keeps AiSOC in sync.
+
+Why this lives in a separate module from ``inbox.py``
+-----------------------------------------------------
+``inbox.py`` is the *operator-facing* management API for tenant inbox
+tokens (mint, list, rotate, revoke). Every route there requires an
+authenticated user with ``connectors:read`` / ``connectors:write``
+permission, because rotating a token is a privileged operation.
+
+This module is the *public webhook receiver*. Authentication is via the
+**inbox token in the URL path**, not via a session cookie or bearer.
+The two have totally different threat models and audit footprints, so
+they live in separate routers (sharing only the ``/inbox`` URL prefix
+to keep operator mental models simple).
+
+Auth model
+----------
+The URL is ``/api/v1/inbox/itsm/{tenant_token}/{connector_instance_id}``,
+where:
+
+* ``tenant_token`` is a row from ``tenant_inbox_tokens`` (template_id
+ must be ``itsm-inbound``). Resolves to a ``tenant_id``.
+* ``connector_instance_id`` is the UUID of a row in ``connectors`` —
+ the specific Jira project / ServiceNow instance whose webhooks are
+ hitting us. We cross-check that the connector's ``tenant_id`` matches
+ the token's ``tenant_id`` so a leaked token from tenant A can't be
+ paired with a connector from tenant B.
+
+Optional second factor: if the operator set ``hmac_secret`` on the
+inbox token, we verify ``X-AiSOC-Signature: sha256=<hex>`` against
+``HMAC(secret, raw_body)`` and reject mismatches.
+
+Idempotency
+-----------
+Vendor webhooks retry aggressively (Jira up to 5×, ServiceNow until
+the destination 200s). Every code path here is structured so that
+re-delivering the same payload is a no-op — we look up the case by
+``(connector_instance_id, external_id)``, compare the inbound status
+to the current AiSOC status, and only write when they actually differ.
+A redelivered "Done" event after we've already closed the case bumps
+``case_external_refs.last_synced_at`` and nothing else.
+
+What we explicitly do NOT do
+----------------------------
+* We do not let the ITSM transition the AiSOC case into states that
+ don't exist in our enum (``new``, ``triaged``, ``investigating``,
+ ``contained``, ``resolved``, ``closed``). Anything we can't map
+ cleanly is treated as "no status change" and the case stays put —
+ but we still bump ``last_synced_at`` so the operator knows the
+ webhook is alive.
+* We do not delete cases when an ITSM ticket is deleted. That's
+ destructive and irreversible; the operator must close the case
+ through AiSOC's own UI.
+* We do not honour assignment / priority changes. They're trivially
+ reversible if we ever want them later, but for now ITSM is only the
+ source of truth for *status*. Comments, custom fields, etc. are
+ one-way (AiSOC → ITSM only).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, Header, HTTPException, Request, status
+from pydantic import BaseModel
+from sqlalchemy import text
+
+from app.api.v1.deps import DBSession
+
+logger = logging.getLogger(__name__)
+
+# Same prefix as ``inbox.py`` (operator-facing) so the public URL is
+# /api/v1/inbox/itsm/.... The two modules share the prefix but not the
+# auth / permission stack — see module docstring.
+router = APIRouter(prefix="/inbox", tags=["inbox-itsm"])
+
+
+# ---------------------------------------------------------------------------
+# Status reverse maps. Inbound (vendor → AiSOC) is intentionally lossy and
+# canonicalising — multiple vendor states collapse onto a single AiSOC state.
+# We keep the maps narrow on purpose:
+#
+# * Lower-case the vendor token before lookup, so "DONE", "Done", and
+# "done" all hit the same row.
+# * Anything we don't recognise returns None and the caller treats that
+# as "no status change" (still bump last_synced_at so operators see the
+# ping landed).
+#
+# These mirror the *forward* maps in
+# ``services/connectors/app/connectors/jira_connector.py`` and
+# ``services/connectors/app/connectors/servicenow.py`` — kept as a
+# duplicate intentionally because:
+#
+# * Forward maps are owned by the connectors microservice (Python AND
+# potentially Go ports later); inbound maps are owned by the API
+# service. Sharing a constant module across the network boundary
+# would couple deploy lifecycles unnecessarily.
+# * The directions are not symmetric (forward has finer granularity
+# than reverse), so keeping them separate makes each half readable.
+# ---------------------------------------------------------------------------
+
+_JIRA_INBOUND_STATUS: dict[str, str] = {
+ # Standard Jira status names. We match against ``status.name`` from the
+ # webhook payload, lower-cased.
+ "to do": "triaged",
+ "open": "triaged",
+ "backlog": "triaged",
+ "selected for development": "triaged",
+ "in progress": "investigating",
+ "in review": "investigating",
+ "blocked": "contained",
+ "on hold": "contained",
+ "resolved": "resolved",
+ "done": "resolved",
+ "closed": "closed",
+ "cancelled": "closed",
+ "canceled": "closed",
+ "won't fix": "closed",
+ "wont fix": "closed",
+ "won't do": "closed",
+}
+
+
+_SNOW_INBOUND_STATUS: dict[str, str] = {
+ # ServiceNow ``state`` is numeric. Mapping from sys_choice list values
+ # for the ``incident`` table:
+ # 1 = New, 2 = In Progress, 3 = On Hold, 6 = Resolved, 7 = Closed,
+ # 8 = Cancelled.
+ "1": "triaged",
+ "2": "investigating",
+ "3": "contained",
+ "6": "resolved",
+ "7": "closed",
+ "8": "closed",
+}
+
+
+# Connector types we accept inbound webhooks from. Anything else 422s — we
+# don't want a misconfigured connector pointing the wrong vendor's webhook
+# at this URL and silently dropping events.
+_SUPPORTED_VENDORS: frozenset[str] = frozenset({"jira", "servicenow"})
+
+
+# Inbox tokens used for ITSM inbound MUST carry this template_id. Operator
+# UI mints tokens with this template specifically so an inbox token minted
+# for, say, PagerDuty alert ingest can't accidentally be repurposed as an
+# ITSM webhook receiver (which would be tenant-scoped but could trigger
+# unwanted status changes on cases).
+_ITSM_TEMPLATE_ID = "itsm-inbound"
+
+
+# ---------------------------------------------------------------------------
+# Lightweight wire schemas — we don't strictly validate the full vendor
+# payload because Jira and ServiceNow both expose long-tail custom fields
+# and rejecting unknown keys would brick operator workflows. We only pull
+# the handful of fields we actually act on.
+# ---------------------------------------------------------------------------
+
+
+class InboundResult(BaseModel):
+ """Response body for the inbound webhook."""
+
+ case_id: uuid.UUID | None
+ """AiSOC case the inbound event mapped to. ``None`` means the external
+ ID wasn't found — the webhook is acknowledged with 200 anyway, because
+ Jira/ServiceNow will retry forever on non-2xx and we don't want one
+ stale ticket to block the queue."""
+
+ case_number: str | None
+ """Operator-friendly handle (e.g. ``CASE-1023``). None when ``case_id``
+ is None or the underlying ``aisoc_cases`` row predates case_number."""
+
+ external_id: str | None
+ """The vendor handle we extracted from the payload (Jira issue key,
+ ServiceNow sys_id). None means we couldn't find one — the payload is
+ malformed and we logged the parse failure."""
+
+ old_status: str | None
+ """AiSOC status before this webhook. None when ``case_id`` is None."""
+
+ new_status: str | None
+ """AiSOC status after applying the inbound transition. Equal to
+ ``old_status`` when the inbound vendor state didn't map to anything
+ actionable, or when the case was already in the target state."""
+
+ status_changed: bool
+ """True iff we wrote a new status onto ``aisoc_cases``."""
+
+ note: str | None = None
+ """Human-readable explanation when nothing happened (unknown external_id,
+ unmapped status, etc.). Useful in webhook delivery logs."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _verify_hmac(
+ *,
+ secret: str | None,
+ raw_body: bytes,
+ signature_header: str | None,
+) -> None:
+ """Reject the request if the inbox token has an HMAC secret and the
+ inbound signature header doesn't match.
+
+ Accepts both ``sha256=<hex>`` (GitHub-style) and bare ``<hex>`` because
+ Jira and ServiceNow's webhook implementations differ. ``hmac.compare_digest``
+ is constant-time.
+
+ No-op when ``secret`` is None — the inbox token in the URL is the only
+ authenticator in that case, which is the correct trust model when the
+ vendor doesn't support HMAC signatures (older ServiceNow installs,
+ bespoke webhook proxies, etc.).
+ """
+ if secret is None:
+ return
+
+ if signature_header is None or not signature_header.strip():
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail="HMAC signature required for this inbox token",
+ )
+
+ sig = signature_header.strip()
+ if sig.lower().startswith("sha256="):
+ sig = sig.split("=", 1)[1].strip()
+
+ expected = hmac.new(
+ secret.encode("utf-8"),
+ raw_body,
+ hashlib.sha256,
+ ).hexdigest()
+
+ if not hmac.compare_digest(sig.lower(), expected.lower()):
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail="Invalid HMAC signature",
+ )
+
+
+def _parse_jira_payload(payload: dict[str, Any]) -> tuple[str | None, str | None]:
+ """Pull ``issue.key`` + ``issue.fields.status.name`` from a Jira webhook.
+
+ Jira posts the full issue under ``issue`` for both ``jira:issue_created``
+ and ``jira:issue_updated`` events. We only act on transitions, so we
+ don't bother distinguishing the two — if there's a status to set, set it.
+
+ Returns ``(external_id, status_name)``. Either or both may be None when
+ the payload is malformed; the caller treats that as a no-op.
+ """
+ issue = payload.get("issue") or {}
+ if not isinstance(issue, dict):
+ return None, None
+
+ key = issue.get("key")
+ if not isinstance(key, str) or not key:
+ return None, None
+
+ fields = issue.get("fields") or {}
+ if not isinstance(fields, dict):
+ return key, None
+
+ status_obj = fields.get("status") or {}
+ if not isinstance(status_obj, dict):
+ return key, None
+
+ name = status_obj.get("name")
+ if not isinstance(name, str):
+ return key, None
+
+ return key, name
+
+
+def _parse_servicenow_payload(
+ payload: dict[str, Any],
+) -> tuple[str | None, str | None]:
+ """Pull ``sys_id`` + ``state`` from a ServiceNow business rule webhook.
+
+ ServiceNow's webhook payloads are operator-configured via a business
+ rule, but the canonical shape is a JSON object whose top-level keys
+ are the column names of the ``incident`` table — same shape as the
+ REST Table API GET response. We accept both that shape and a thin
+ wrapper of ``{"current": {...}}`` (the form used when the operator
+ forwards the BR's ``current`` GlideRecord directly).
+
+ State is normalised to a string so the lookup against
+ ``_SNOW_INBOUND_STATUS`` works for both ``"6"`` and ``6``.
+ """
+ record = payload.get("current") if "current" in payload else payload
+ if not isinstance(record, dict):
+ return None, None
+
+ sys_id = record.get("sys_id")
+ if not isinstance(sys_id, str) or not sys_id:
+ # ServiceNow always populates sys_id; if it's missing the payload
+ # is from a BR that didn't include it and we can't correlate.
+ return None, None
+
+ state = record.get("state")
+ if state is None:
+ return sys_id, None
+
+ return sys_id, str(state)
+
+
+def _map_inbound_status(vendor: str, raw_status: str | None) -> str | None:
+ """Look up the AiSOC equivalent of a vendor status, or None.
+
+ Returns None for both "vendor returned no status" and "we don't know
+ how to map it" — they're the same outcome from the caller's point of
+ view (don't change the AiSOC status).
+ """
+ if raw_status is None:
+ return None
+ if vendor == "jira":
+ return _JIRA_INBOUND_STATUS.get(raw_status.strip().lower())
+ if vendor == "servicenow":
+ return _SNOW_INBOUND_STATUS.get(raw_status.strip())
+ return None
+
+
+async def _fetch_token_and_connector(
+ db: Any,
+ *,
+ tenant_token: str,
+ connector_instance_id: uuid.UUID,
+) -> tuple[Any, Any]:
+ """Resolve the inbox token and connector instance, verifying tenant match.
+
+ Returns ``(inbox_token_row, connector_row)``. Raises 401/404 on missing
+ or mismatched rows so the caller can stay focused on payload handling.
+
+ The two lookups are deliberately separate queries (instead of a single
+ JOIN) because:
+
+ * They have different cache profiles — the token row is read on every
+ webhook delivery, the connector row changes when the operator edits
+ auth_config / the OAuth refresh worker runs.
+ * 401 vs 404 carries different signal: a missing token is "this URL
+ was revoked or never existed", a missing connector is "the operator
+ detached this integration but forgot to update the vendor webhook".
+ Distinguishing them helps webhook delivery debugging.
+ """
+ # 1. Resolve the token. We require revoked_at IS NULL — once an
+ # operator rotates the token, the old one MUST stop accepting traffic.
+ token_row = (
+ await db.execute(
+ text(
+ """
+ SELECT token, tenant_id, template_id, hmac_secret, revoked_at
+ FROM tenant_inbox_tokens
+ WHERE token = :token AND revoked_at IS NULL
+ """
+ ).bindparams(token=tenant_token)
+ )
+ ).fetchone()
+ if token_row is None:
+ # Don't echo the token in the error — even the trailing 8 chars
+ # would help an attacker confirm a guess. The structlog event
+ # carries the fingerprint for ops debugging.
+ logger.info(
+ "inbox_itsm.token_not_found",
+ extra={"token_fingerprint": f"...{tenant_token[-8:]}"},
+ )
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail="Invalid or revoked inbox token",
+ )
+
+ if token_row.template_id != _ITSM_TEMPLATE_ID:
+ # An operator paired a vendor's ITSM webhook with an inbox token
+ # minted for a different purpose (e.g. PagerDuty alert ingest).
+ # We refuse to act on it — let the wizard mint a fresh ITSM token.
+ raise HTTPException(
+ status_code=status.HTTP_403_FORBIDDEN,
+ detail=(
+ "Inbox token is not valid for ITSM webhooks. "
+ "Mint a token with template_id='itsm-inbound'."
+ ),
+ )
+
+ # 2. Resolve the connector. tenant_id check below prevents using a
+ # token from one tenant against a connector from another.
+ connector_row = (
+ await db.execute(
+ text(
+ """
+ SELECT id, tenant_id, connector_type, enabled
+ FROM connectors
+ WHERE id = :id
+ """
+ ).bindparams(id=connector_instance_id)
+ )
+ ).fetchone()
+ if connector_row is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail="Connector instance not found",
+ )
+
+ if connector_row.tenant_id != token_row.tenant_id:
+ # Cross-tenant attempt — log loudly so the SOC can investigate.
+ logger.warning(
+ "inbox_itsm.cross_tenant_attempt",
+ extra={
+ "token_tenant_id": str(token_row.tenant_id),
+ "connector_tenant_id": str(connector_row.tenant_id),
+ "connector_id": str(connector_instance_id),
+ },
+ )
+ raise HTTPException(
+ status_code=status.HTTP_403_FORBIDDEN,
+ detail="Token and connector belong to different tenants",
+ )
+
+ if not connector_row.enabled:
+ # A disabled connector should not be receiving traffic. Prefer 409
+ # over 200 here so the vendor's webhook delivery dashboard surfaces
+ # the issue instead of silently consuming the events.
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT,
+ detail="Connector instance is disabled",
+ )
+
+ if connector_row.connector_type not in _SUPPORTED_VENDORS:
+ raise HTTPException(
+ status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+ detail=(
+ f"connector_type '{connector_row.connector_type}' is not "
+ "supported on the inbound ITSM webhook. "
+ f"Supported: {', '.join(sorted(_SUPPORTED_VENDORS))}."
+ ),
+ )
+
+ return token_row, connector_row
+
+
+async def _apply_status_to_case(
+ db: Any,
+ *,
+ case_row: Any,
+ new_status: str,
+ actor_label: str,
+ external_id: str,
+ vendor: str,
+) -> None:
+ """Mirror an inbound status onto ``aisoc_cases`` + write a system note.
+
+ Three writes in one transaction (the caller commits):
+
+ 1. ``aisoc_cases``: status, updated_at, plus the timeline columns
+ (``triaged_at`` / ``resolved_at`` / ``closed_at``) the appropriate
+ transition implies. Mirrors the logic in
+ ``cases.update_case`` so AiSOC's own audit math stays consistent.
+ 2. ``case_external_refs``: ``external_status`` + ``last_synced_at``.
+ This is what makes the *next* outbound ``push_status_change`` a
+ no-op — the connector compares ``external_status`` to the desired
+ state and short-circuits when they already match.
+ 3. ``aisoc_case_comments``: a system note ("ServiceNow set state to
+ Resolved → AiSOC case marked resolved") so the timeline view shows
+ the inbound transition with its provenance.
+
+ The caller has already verified ``new_status`` is in the allowed set,
+ so we don't re-validate here.
+ """
+ now = datetime.now(UTC)
+
+ # Map status → which timeline column to bump. We never *clear* a column
+ # — once a case has been triaged, the timestamp stays even if it later
+ # moves back to "new" (which the inbound flow can't actually do
+ # anyway, but defending in depth is cheap). COALESCE keeps the first
+ # transition's timestamp.
+ triaged_at_set = (
+ ", triaged_at = COALESCE(triaged_at, :now)"
+ if new_status in {"triaged", "investigating", "contained", "resolved", "closed"}
+ else ""
+ )
+ resolved_at_set = (
+ ", resolved_at = COALESCE(resolved_at, :now)"
+ if new_status == "resolved"
+ else ""
+ )
+ closed_at_set = (
+ ", closed_at = COALESCE(closed_at, :now)"
+ if new_status == "closed"
+ else ""
+ )
+
+ await db.execute(
+ text(
+ f"""
+ UPDATE aisoc_cases
+ SET status = :status,
+ updated_at = :now
+ {triaged_at_set}
+ {resolved_at_set}
+ {closed_at_set}
+ WHERE id = :id
+ """
+ ).bindparams(status=new_status, now=now, id=case_row.id)
+ )
+
+ await db.execute(
+ text(
+ """
+ UPDATE case_external_refs
+ SET external_status = :ext_status,
+ last_synced_at = :now,
+ updated_at = :now
+ WHERE case_id = :case_id AND external_id = :external_id
+ """
+ ).bindparams(
+ ext_status=new_status,
+ now=now,
+ case_id=case_row.id,
+ external_id=external_id,
+ )
+ )
+
+ note_body = (
+ f"{vendor.title()} ticket {external_id} transitioned. "
+ f"AiSOC case marked '{new_status}' via inbound webhook."
+ )
+ await db.execute(
+ text(
+ """
+ INSERT INTO aisoc_case_comments
+ (id, case_id, author, body, is_system, created_at)
+ VALUES
+ (:id, :case_id, :author, :body, TRUE, :now)
+ """
+ ).bindparams(
+ id=uuid.uuid4(),
+ case_id=case_row.id,
+ author=actor_label,
+ body=note_body,
+ now=now,
+ )
+ )
+
+
+# ---------------------------------------------------------------------------
+# Endpoint
+# ---------------------------------------------------------------------------
+
+
+ "/itsm/{tenant_token}/{connector_instance_id}",
+ response_model=InboundResult,
+ summary="Inbound ITSM webhook (Jira / ServiceNow → AiSOC case)",
+)
+async def inbound_itsm_webhook(
+ tenant_token: str,
+ connector_instance_id: uuid.UUID,
+ request: Request,
+ db: DBSession,
+ x_aisoc_signature: str | None = Header(default=None, alias="X-AiSOC-Signature"),
+) -> InboundResult:
+ """Receive a Jira / ServiceNow webhook and mirror status onto AiSOC.
+
+ Public-facing — the only authenticator is the ``tenant_token`` in the
+ URL (and an optional ``X-AiSOC-Signature`` HMAC). Rate limiting and
+ DDoS protection are expected to live at the edge (Cloudflare /
+ upstream LB), not here — the vendor's source IPs are stable enough
+ that the ops team can configure WAF rules.
+
+ Always returns 200 (never 5xx) on the happy path, even when the
+ payload doesn't map to anything actionable. Vendor webhook
+ implementations retry forever on non-2xx, and a stale ticket pinging
+ a long-deleted case shouldn't block the rest of the queue. We surface
+ "nothing happened" via ``InboundResult.status_changed=False`` and a
+ human-readable ``note``.
+ """
+
+ raw_body = await request.body()
+
+ token_row, connector_row = await _fetch_token_and_connector(
+ db,
+ tenant_token=tenant_token,
+ connector_instance_id=connector_instance_id,
+ )
+
+ _verify_hmac(
+ secret=token_row.hmac_secret,
+ raw_body=raw_body,
+ signature_header=x_aisoc_signature,
+ )
+
+ # Parse JSON ourselves so we get the raw body for HMAC verification
+ # *before* JSON parsing ever runs. ``request.json()`` would consume
+ # the stream and we'd have nothing to verify against.
+ try:
+ import json
+
+ payload = json.loads(raw_body or b"{}")
+ except json.JSONDecodeError as exc:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=f"Webhook body is not valid JSON: {exc.msg}",
+ ) from exc
+ if not isinstance(payload, dict):
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail="Webhook body must be a JSON object",
+ )
+
+ vendor = connector_row.connector_type
+ if vendor == "jira":
+ external_id, raw_status = _parse_jira_payload(payload)
+ elif vendor == "servicenow":
+ external_id, raw_status = _parse_servicenow_payload(payload)
+ else:
+ # Already filtered in _fetch_token_and_connector but be defensive —
+ # the tuple of supported vendors is the only place this list is
+ # ever updated.
+ raise HTTPException(
+ status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+ detail=f"unsupported vendor: {vendor}",
+ )
+
+ if external_id is None:
+ # Malformed payload — log the connector so ops can debug, but
+ # 200 the vendor so they don't retry endlessly. We saw this in
+ # the wild when ServiceNow business rules emit synthetic
+ # "current=null" events on initial deploy.
+ logger.info(
+ "inbox_itsm.payload_missing_external_id",
+ extra={
+ "vendor": vendor,
+ "connector_id": str(connector_instance_id),
+ "tenant_id": str(token_row.tenant_id),
+ },
+ )
+ return InboundResult(
+ case_id=None,
+ case_number=None,
+ external_id=None,
+ old_status=None,
+ new_status=None,
+ status_changed=False,
+ note=f"{vendor} payload missing required fields",
+ )
+
+ # Resolve external_id → AiSOC case via case_external_refs. The unique
+ # constraint on (connector_instance_id, external_id) guarantees at
+ # most one row.
+ ref_row = (
+ await db.execute(
+ text(
+ """
+ SELECT r.id, r.case_id, r.external_status,
+ c.id AS aisoc_case_id, c.case_number, c.status
+ FROM case_external_refs r
+ JOIN aisoc_cases c ON c.id = r.case_id
+ WHERE r.connector_instance_id = :connector_id
+ AND r.external_id = :external_id
+ """
+ ).bindparams(
+ connector_id=connector_instance_id,
+ external_id=external_id,
+ )
+ )
+ ).fetchone()
+
+ if ref_row is None:
+ # ITSM ticket exists on the vendor side but we don't have it
+ # linked to any AiSOC case. This is normal during onboarding
+ # (operator imported pre-existing tickets) — bump nothing, log,
+ # and 200 the vendor.
+ logger.info(
+ "inbox_itsm.unlinked_external_id",
+ extra={
+ "vendor": vendor,
+ "external_id": external_id,
+ "connector_id": str(connector_instance_id),
+ "tenant_id": str(token_row.tenant_id),
+ },
+ )
+ return InboundResult(
+ case_id=None,
+ case_number=None,
+ external_id=external_id,
+ old_status=None,
+ new_status=None,
+ status_changed=False,
+ note=(
+ f"No AiSOC case linked to {vendor} {external_id}. "
+ "The ticket may pre-date the integration."
+ ),
+ )
+
+ # Update last_used_at on the inbox token regardless of whether the
+ # status changed, so operators can see "this token is alive". Done
+ # on every successful auth+resolve, not just on writes.
+ now = datetime.now(UTC)
+ await db.execute(
+ text(
+ "UPDATE tenant_inbox_tokens SET last_used_at = :now WHERE token = :tok"
+ ).bindparams(now=now, tok=tenant_token)
+ )
+
+ new_status = _map_inbound_status(vendor, raw_status)
+ if new_status is None:
+ # Either the vendor sent no status field or we don't have a
+ # mapping for it. Bump last_synced_at so the timeline shows the
+ # ping landed but don't change the case.
+ await db.execute(
+ text(
+ """
+ UPDATE case_external_refs
+ SET last_synced_at = :now, updated_at = :now
+ WHERE id = :id
+ """
+ ).bindparams(now=now, id=ref_row.id)
+ )
+ await db.commit()
+ return InboundResult(
+ case_id=ref_row.aisoc_case_id,
+ case_number=ref_row.case_number,
+ external_id=external_id,
+ old_status=ref_row.status,
+ new_status=ref_row.status,
+ status_changed=False,
+ note=(
+ f"{vendor} status '{raw_status}' has no AiSOC equivalent; "
+ "last_synced_at bumped."
+ ),
+ )
+
+ if new_status == ref_row.status:
+ # Idempotent redelivery — case is already in the target state.
+ # Touch sync columns and return.
+ await db.execute(
+ text(
+ """
+ UPDATE case_external_refs
+ SET external_status = :ext_status,
+ last_synced_at = :now,
+ updated_at = :now
+ WHERE id = :id
+ """
+ ).bindparams(ext_status=new_status, now=now, id=ref_row.id)
+ )
+ await db.commit()
+ return InboundResult(
+ case_id=ref_row.aisoc_case_id,
+ case_number=ref_row.case_number,
+ external_id=external_id,
+ old_status=ref_row.status,
+ new_status=new_status,
+ status_changed=False,
+ note="Case already in target state; sync timestamps refreshed.",
+ )
+
+ # Real status change. The actor label leaks the connector_type only,
+ # never the full URL or sys_id — that detail goes in the body of the
+ # system comment.
+ actor_label = f"itsm-webhook ({vendor})"
+ try:
+ await _apply_status_to_case(
+ db,
+ case_row=ref_row,
+ new_status=new_status,
+ actor_label=actor_label,
+ external_id=external_id,
+ vendor=vendor,
+ )
+ await db.commit()
+ except Exception as exc:
+ await db.rollback()
+ logger.exception(
+ "inbox_itsm.apply_failed",
+ extra={
+ "vendor": vendor,
+ "external_id": external_id,
+ "case_id": str(ref_row.aisoc_case_id),
+ },
+ )
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail=f"Failed to apply inbound status: {exc}",
+ ) from exc
+
+ logger.info(
+ "inbox_itsm.status_applied",
+ extra={
+ "vendor": vendor,
+ "external_id": external_id,
+ "case_id": str(ref_row.aisoc_case_id),
+ "old_status": ref_row.status,
+ "new_status": new_status,
+ },
+ )
+ return InboundResult(
+ case_id=ref_row.aisoc_case_id,
+ case_number=ref_row.case_number,
+ external_id=external_id,
+ old_status=ref_row.status,
+ new_status=new_status,
+ status_changed=True,
+ )
diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.py
index 1f9ab66bb..532768fe4 100644
--- a/services/api/app/api/v1/router.py
+++ b/services/api/app/api/v1/router.py
@@ -28,6 +28,7 @@ from app.api.v1.endpoints import (
hunts,
identity_timeline,
inbox,
+ inbox_itsm,
knowledge_base,
lake,
nl_detection,
@@ -166,6 +167,15 @@ api_router.include_router(agents.router)
# tenant + template_id and reuses the existing OCSF normalizer.
api_router.include_router(inbox.router)
+# Bidirectional ITSM webhook receiver (Workstream 8 of AI Stack plan).
+# /inbox/itsm/{tenant_token}/{connector_instance_id} accepts inbound
+# Jira / ServiceNow webhooks, resolves the external ticket back to its
+# AiSOC case via case_external_refs, and mirrors the status onto
+# aisoc_cases. This is the *inbound* counterpart to case_fanout (which
+# handles outbound AiSOC → ITSM projection) and is what makes the
+# operator's existing ITSM the source of truth for case status.
+api_router.include_router(inbox_itsm.router)
+
# Tenant lake API (Workstream 7 of AI Stack plan).
# /lake/sql executes a tenant-scoped SELECT against the warm tier
# (ClickHouse) after passing through the SQL rewriter, which enforces a
diff --git a/services/api/tests/test_case_fanout.py b/services/api/tests/test_case_fanout.py
new file mode 100644
index 000000000..265e697d5
--- /dev/null
+++ b/services/api/tests/test_case_fanout.py
@@ -0,0 +1,678 @@
+"""Unit tests for the case → ITSM fan-out service (Workstream 8).
+
+The fan-out service projects AiSOC case lifecycle events onto external
+ITSM systems via the connectors microservice. The behaviour we care
+about most:
+
+* ``_serialize_case_for_push`` — converts ORM rows / mappings into a
+ bounded payload (no observable_graph, no evidence_chain) so a noisy
+ Jira logger can't accidentally exfiltrate intra-tenant data.
+* ``_post_to_connector_service`` — wraps every ``httpx`` failure mode
+ into a tagged status string so the calling endpoint never has to
+ catch transport errors itself.
+* ``fanout_create_case`` — happy path, vault decrypt failure, 501
+ unsupported, transport error, missing ``external_id`` in body.
+* ``fanout_status_change`` — walks ``case_external_refs``, surfaces
+ orphaned refs as ``skipped`` (FK is on case_id, not connector_id),
+ and updates the persisted ``external_status``.
+
+We mock the AsyncSession the same way ``test_inbox_itsm_endpoint`` does
+— a ``MagicMock`` with ``execute`` as ``AsyncMock`` — and patch ``httpx``
++ the credential vault rather than booting the full FastAPI app. That
+keeps each test focused on a single decision branch in the fan-out
+state machine.
+"""
+
+from __future__ import annotations
+
+import uuid
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+from app.services.case_fanout import (
+ FanoutResult,
+ ITSM_PUSH_CAPABLE_TYPES,
+ _post_to_connector_service,
+ _push_case_url,
+ _push_status_url,
+ _serialize_case_for_push,
+ fanout_create_case,
+ fanout_status_change,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_connector(
+ *,
+ connector_id: uuid.UUID | None = None,
+ connector_type: str = "jira",
+ name: str = "Jira (Prod)",
+ auth_config: dict[str, Any] | None = None,
+ connector_config: dict[str, Any] | None = None,
+ is_enabled: bool = True,
+ tenant_id: uuid.UUID | None = None,
+) -> SimpleNamespace:
+ """Build a minimal ORM-shaped Connector stub.
+
+ SimpleNamespace mirrors the attribute access pattern the fan-out
+ code uses (``connector.id``, ``connector.connector_type``, …) so we
+ don't need to instantiate the real SQLAlchemy model and risk session
+ binding side-effects.
+ """
+ return SimpleNamespace(
+ id=connector_id or uuid.uuid4(),
+ tenant_id=tenant_id or uuid.uuid4(),
+ connector_type=connector_type,
+ name=name,
+ is_enabled=is_enabled,
+ auth_config=auth_config or {"api_token": "vault:v1:zzz"},
+ connector_config=connector_config or {"site_url": "https://example.atlassian.net"},
+ )
+
+
+def _make_case_row(
+ *,
+ case_id: uuid.UUID | None = None,
+ status: str = "open",
+ title: str = "Phishing wave from acme.bad",
+ severity: str = "high",
+) -> dict[str, Any]:
+ """Build a case row with the columns ``_serialize_case_for_push`` reads.
+
+ We return a plain dict because ``_serialize_case_for_push`` accepts
+ ORM Row (with ``_mapping``) or dict — not raw SimpleNamespace. The
+ serializer reads the ``id``/``status``/``title`` columns and ignores
+ everything else, so we deliberately include ``observable_graph`` and
+ ``evidence_chain`` as honeypots: if they ever appear in the output
+ payload, the ``_serialize_case_for_push_drops_internal_fields`` test
+ will fail.
+ """
+ return {
+ "id": case_id or uuid.uuid4(),
+ "case_number": "AISOC-1234",
+ "title": title,
+ "description": "Operator notes",
+ "severity": severity,
+ "status": status,
+ "assignee": None,
+ "tags": {"env": "prod"},
+ "mitre_techniques": ["T1566"],
+ # Honeypot fields — must NOT be in serialized payload.
+ "observable_graph": {"nodes": ["leak"]},
+ "evidence_chain": [{"hash": "secret"}],
+ }
+
+
+def _build_db_with_connectors(
+ connectors: list[Any],
+ refs: list[dict[str, Any]] | None = None,
+) -> Any:
+ """Build a MagicMock DB session that replays the queries fan-out runs.
+
+ ``fanout_create_case`` issues exactly one ``select(Connector)``
+ followed by zero-or-more ``_upsert_external_ref`` writes. We set up
+ ``side_effect`` on ``execute`` so the ``select`` returns a result
+ whose ``.scalars().all()`` matches ``connectors``, and subsequent
+ INSERT calls just return a no-op MagicMock.
+
+ ``fanout_status_change`` issues:
+ 1. a ``SELECT`` against ``case_external_refs`` returning ``refs``,
+ 2. a ``select(Connector)`` returning ``connectors``,
+ 3. one ``INSERT … ON CONFLICT`` per ref.
+
+ We let any extra ``execute`` calls fall through to a plain MagicMock
+ so writes don't blow up the test even if the count drifts by one.
+ """
+ db = MagicMock()
+ select_result = MagicMock()
+ select_result.scalars.return_value.all.return_value = list(connectors)
+
+ refs_result = MagicMock()
+ refs_result.fetchall.return_value = [
+ SimpleNamespace(_mapping=ref) for ref in (refs or [])
+ ]
+
+ side_effects: list[Any] = []
+ if refs is not None:
+ # Status-change path: refs first, connectors second, then writes.
+ side_effects.append(refs_result)
+ side_effects.append(select_result)
+ # Pad out write responses; AsyncMock side_effect runs out → re-uses
+ # the last entry only if it's a callable, so we explicitly pad.
+ for _ in range(8):
+ side_effects.append(MagicMock())
+
+ db.execute = AsyncMock(side_effect=side_effects)
+ return db
+
+
+def _build_post_response(
+ *,
+ status_code: int = 200,
+ json_body: dict[str, Any] | None = None,
+ text_body: str | None = None,
+) -> Any:
+ """Build a fake httpx Response. Avoids the real Response constructor
+ so we can drive ``resp.json()`` / ``resp.text`` shape directly."""
+ resp = MagicMock()
+ resp.status_code = status_code
+ resp.content = b"non-empty" if (json_body is not None or text_body) else b""
+ if json_body is not None:
+ resp.json.return_value = json_body
+ else:
+ resp.json.side_effect = ValueError("no json")
+ resp.text = text_body or ""
+ return resp
+
+
+# ---------------------------------------------------------------------------
+# URL helpers
+# ---------------------------------------------------------------------------
+
+
+def test_push_case_url_uses_connectors_service_base() -> None:
+ url = _push_case_url("jira")
+ assert url.endswith("/api/v1/connectors/jira/push_case")
+
+
+def test_push_status_url_uses_connectors_service_base() -> None:
+ url = _push_status_url("servicenow")
+ assert url.endswith("/api/v1/connectors/servicenow/push_status_change")
+
+
+def test_itsm_push_capable_types_is_locked_down() -> None:
+ """The allow-list MUST stay tight. Adding a new connector here
+ enables fan-out for that vendor; do not relax casually."""
+ assert ITSM_PUSH_CAPABLE_TYPES == frozenset({"jira", "servicenow"})
+
+
+# ---------------------------------------------------------------------------
+# _serialize_case_for_push
+# ---------------------------------------------------------------------------
+
+
+def test_serialize_case_for_push_drops_internal_fields() -> None:
+ """Observable graph + evidence chain must NEVER be in the outbound
+ payload. A misconfigured Jira logger that dumps the request body
+ would leak intra-tenant graph data otherwise."""
+ case = _make_case_row()
+ payload = _serialize_case_for_push(case)
+ assert "observable_graph" not in payload
+ assert "evidence_chain" not in payload
+ assert payload["title"] == case["title"]
+ assert payload["status"] == case["status"]
+ assert payload["mitre_techniques"] == ["T1566"]
+ assert payload["tags"] == {"env": "prod"}
+
+
+def test_serialize_case_for_push_handles_dict_input() -> None:
+ case_id = uuid.uuid4()
+ payload = _serialize_case_for_push(
+ {"id": case_id, "title": "T", "status": "open", "severity": "low"}
+ )
+ assert payload["id"] == str(case_id)
+ assert payload["title"] == "T"
+ # Defaults for unset list/dict columns.
+ assert payload["tags"] == {}
+ assert payload["mitre_techniques"] == []
+
+
+def test_serialize_case_for_push_handles_row_with_mapping() -> None:
+ """SQLAlchemy returns ``Row`` with ``_mapping`` for raw text() results.
+ The serializer must accept both ORM-style attribute access and the
+ Row mapping protocol."""
+ case_id = uuid.uuid4()
+ row = SimpleNamespace(_mapping={"id": case_id, "title": "from-row", "status": "closed"})
+ payload = _serialize_case_for_push(row)
+ assert payload["id"] == str(case_id)
+ assert payload["title"] == "from-row"
+
+
+# ---------------------------------------------------------------------------
+# _post_to_connector_service
+# ---------------------------------------------------------------------------
+
+
+async def test_post_returns_ok_on_2xx() -> None:
+ fake_resp = _build_post_response(
+ status_code=200,
+ json_body={"external_id": "AIS-1", "vendor": "jira"},
+ )
+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ status, body, err = await _post_to_connector_service(
+ url="http://x/y", payload={}, timeout_seconds=5.0
+ )
+ assert status == "ok"
+ assert body == {"external_id": "AIS-1", "vendor": "jira"}
+ assert err is None
+
+
+async def test_post_returns_unsupported_on_501() -> None:
+ fake_resp = _build_post_response(status_code=501, text_body="capability missing")
+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ status, body, err = await _post_to_connector_service(
+ url="http://x/y", payload={}, timeout_seconds=5.0
+ )
+ assert status == "unsupported"
+ assert body is None
+ assert err == "capability missing"
+
+
+async def test_post_returns_error_on_4xx_with_detail() -> None:
+ fake_resp = _build_post_response(
+ status_code=400,
+ json_body={"detail": "missing project_key"},
+ )
+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ status, body, err = await _post_to_connector_service(
+ url="http://x/y", payload={}, timeout_seconds=5.0
+ )
+ assert status == "error"
+ assert body is None
+ assert "missing project_key" in (err or "")
+
+
+async def test_post_returns_error_on_transport_failure() -> None:
+ """``httpx.HTTPError`` (DNS, refused, timeout) must NOT escape.
+
+ Fan-out is best-effort; a flaky Jira tenant must not 503 the case
+ create endpoint."""
+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ side_effect=httpx.ConnectError("dns failed")
+ )
+ status, body, err = await _post_to_connector_service(
+ url="http://x/y", payload={}, timeout_seconds=5.0
+ )
+ assert status == "error"
+ assert body is None
+ assert "connectors service unreachable" in (err or "")
+
+
+async def test_post_returns_error_on_non_dict_body() -> None:
+ """A connectors service that returns ``[1,2,3]`` is buggy. Surface
+ that as an error rather than crashing further down with KeyError."""
+ fake_resp = _build_post_response(status_code=200, json_body=[1, 2, 3]) # type: ignore[arg-type]
+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ status, body, err = await _post_to_connector_service(
+ url="http://x/y", payload={}, timeout_seconds=5.0
+ )
+ assert status == "error"
+ assert "unexpected payload shape" in (err or "")
+
+
+# ---------------------------------------------------------------------------
+# fanout_create_case
+# ---------------------------------------------------------------------------
+
+
+async def test_fanout_create_case_returns_empty_when_no_connectors() -> None:
+ """Common case: operator created a case without selecting any
+ connectors. We must NOT contact the connectors service at all."""
+ db = MagicMock()
+ db.execute = AsyncMock()
+ case = _make_case_row()
+ results = await fanout_create_case(
+ db,
+ case_row=case,
+ tenant_id=uuid.uuid4(),
+ connector_ids=[],
+ )
+ assert results == []
+ assert db.execute.await_count == 0
+
+
+async def test_fanout_create_case_happy_path_persists_external_ref() -> None:
+ """End-to-end: vault decrypts → connectors POST returns external_id
+ → ``case_external_refs`` row gets upserted → ``FanoutResult`` carries
+ the external linkage back to the caller."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row()
+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)
+ db = _build_db_with_connectors([connector])
+
+ fake_resp = _build_post_response(
+ status_code=200,
+ json_body={
+ "external_id": "AIS-42",
+ "external_url": "https://example.atlassian.net/browse/AIS-42",
+ "vendor": "jira",
+ "external_status": "To Do",
+ },
+ )
+
+ with (
+ patch("app.services.case_fanout.get_vault") as mock_vault,
+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,
+ ):
+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ results = await fanout_create_case(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ connector_ids=[connector.id],
+ pushed_by="[email protected]",
+ )
+
+ assert len(results) == 1
+ result = results[0]
+ assert result.status == "ok"
+ assert result.external_id == "AIS-42"
+ assert result.external_url == "https://example.atlassian.net/browse/AIS-42"
+ assert result.connector_type == "jira"
+ # 1 select + 1 upsert.
+ assert db.execute.await_count >= 2
+
+
+async def test_fanout_create_case_credential_vault_failure_short_circuits() -> None:
+ """When vault decryption fails we MUST NOT POST to the connectors
+ service — the auth_config dict in transit would still be ciphertext.
+ Surface the failure as an ``error`` FanoutResult."""
+ from app.security.credential_vault import CredentialVaultError
+
+ tenant_id = uuid.uuid4()
+ case = _make_case_row()
+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)
+ db = _build_db_with_connectors([connector])
+
+ with (
+ patch("app.services.case_fanout.get_vault") as mock_vault,
+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,
+ ):
+ mock_vault.return_value.decrypt_dict.side_effect = CredentialVaultError(
+ "key rotated"
+ )
+ post_mock = AsyncMock()
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ results = await fanout_create_case(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ connector_ids=[connector.id],
+ )
+
+ assert len(results) == 1
+ assert results[0].status == "error"
+ assert "credential decryption failed" in (results[0].error or "")
+ post_mock.assert_not_awaited()
+
+
+async def test_fanout_create_case_unsupported_capability_is_recorded() -> None:
+ """A 501 from the connectors service means the connector type
+ doesn't declare ``Capability.PUSH_CASE``. We surface ``unsupported``
+ rather than treating that as a hard error."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row()
+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)
+ db = _build_db_with_connectors([connector])
+
+ fake_resp = _build_post_response(status_code=501, text_body="not supported")
+ with (
+ patch("app.services.case_fanout.get_vault") as mock_vault,
+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,
+ ):
+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ results = await fanout_create_case(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ connector_ids=[connector.id],
+ )
+
+ assert len(results) == 1
+ assert results[0].status == "unsupported"
+ assert results[0].external_id is None
+
+
+async def test_fanout_create_case_missing_external_id_is_error() -> None:
+ """If the connectors service returns 200 but no ``external_id``,
+ we have nothing useful to persist. Don't write a malformed row to
+ ``case_external_refs``; surface as an error instead."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row()
+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)
+ db = _build_db_with_connectors([connector])
+
+ fake_resp = _build_post_response(
+ status_code=200,
+ json_body={"vendor": "jira"}, # no external_id!
+ )
+ with (
+ patch("app.services.case_fanout.get_vault") as mock_vault,
+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,
+ ):
+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ results = await fanout_create_case(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ connector_ids=[connector.id],
+ )
+
+ assert len(results) == 1
+ assert results[0].status == "error"
+ assert "external_id" in (results[0].error or "")
+
+
+# ---------------------------------------------------------------------------
+# fanout_status_change
+# ---------------------------------------------------------------------------
+
+
+async def test_fanout_status_change_no_refs_means_no_push() -> None:
+ """Cases that were never pushed to any ITSM have no rows in
+ ``case_external_refs``. The status change is a no-op for fan-out
+ — the connectors service never gets called."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row()
+ db = _build_db_with_connectors(connectors=[], refs=[])
+
+ with patch("app.services.case_fanout.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock()
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ results = await fanout_status_change(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ old_status="open",
+ new_status="resolved",
+ )
+
+ assert results == []
+ post_mock.assert_not_awaited()
+
+
+async def test_fanout_status_change_orphaned_ref_is_skipped() -> None:
+ """The connector instance was deleted but the external_ref row
+ survived (FK is on case_id). Surface as ``skipped`` so operators
+ can see the orphan and either re-link or clean up."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row()
+ orphan_connector_id = uuid.uuid4()
+ refs = [
+ {
+ "id": uuid.uuid4(),
+ "case_id": case["id"],
+ "connector_instance_id": orphan_connector_id,
+ "vendor": "jira",
+ "external_id": "AIS-99",
+ "external_url": "https://example/browse/AIS-99",
+ "external_status": "Done",
+ }
+ ]
+ # No matching connector in the live ``connectors`` table.
+ db = _build_db_with_connectors(connectors=[], refs=refs)
+
+ results = await fanout_status_change(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ old_status="open",
+ new_status="resolved",
+ )
+
+ assert len(results) == 1
+ assert results[0].status == "skipped"
+ assert results[0].external_id == "AIS-99"
+ assert "no longer exists" in (results[0].error or "")
+
+
+async def test_fanout_status_change_happy_path_updates_external_status() -> None:
+ """End-to-end: ref lookup → connector lookup → POST to
+ ``push_status_change`` → upsert refreshed ``external_status``."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row(status="resolved")
+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)
+ refs = [
+ {
+ "id": uuid.uuid4(),
+ "case_id": case["id"],
+ "connector_instance_id": connector.id,
+ "vendor": "jira",
+ "external_id": "AIS-7",
+ "external_url": "https://example/browse/AIS-7",
+ "external_status": "In Progress",
+ }
+ ]
+ db = _build_db_with_connectors([connector], refs=refs)
+
+ fake_resp = _build_post_response(
+ status_code=200,
+ json_body={
+ "external_id": "AIS-7",
+ "vendor": "jira",
+ "external_url": "https://example/browse/AIS-7",
+ "external_status": "Done",
+ },
+ )
+
+ with (
+ patch("app.services.case_fanout.get_vault") as mock_vault,
+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,
+ ):
+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=fake_resp
+ )
+ results = await fanout_status_change(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ old_status="open",
+ new_status="resolved",
+ pushed_by="[email protected]",
+ )
+
+ assert len(results) == 1
+ assert results[0].status == "ok"
+ assert results[0].external_id == "AIS-7"
+ assert results[0].external_status == "Done"
+
+
+async def test_fanout_status_change_transport_error_records_failure() -> None:
+ """A network error pushing the status change must surface as
+ ``error`` with the external_id preserved, so the UI can show
+ 'Jira ✗ (timeout)' next to AIS-7 instead of dropping the linkage."""
+ tenant_id = uuid.uuid4()
+ case = _make_case_row(status="resolved")
+ connector = _make_connector(connector_type="jira", tenant_id=tenant_id)
+ refs = [
+ {
+ "id": uuid.uuid4(),
+ "case_id": case["id"],
+ "connector_instance_id": connector.id,
+ "vendor": "jira",
+ "external_id": "AIS-7",
+ "external_url": "https://example/browse/AIS-7",
+ "external_status": "In Progress",
+ }
+ ]
+ db = _build_db_with_connectors([connector], refs=refs)
+
+ with (
+ patch("app.services.case_fanout.get_vault") as mock_vault,
+ patch("app.services.case_fanout.httpx.AsyncClient") as mock_client,
+ ):
+ mock_vault.return_value.decrypt_dict.return_value = {"api_token": "plain"}
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ side_effect=httpx.ReadTimeout("read timed out")
+ )
+ results = await fanout_status_change(
+ db,
+ case_row=case,
+ tenant_id=tenant_id,
+ old_status="open",
+ new_status="resolved",
+ )
+
+ assert len(results) == 1
+ assert results[0].status == "error"
+ assert results[0].external_id == "AIS-7"
+ assert "unreachable" in (results[0].error or "")
+
+
+# ---------------------------------------------------------------------------
+# FanoutResult contract
+# ---------------------------------------------------------------------------
+
+
+def test_fanout_result_serializable_for_api_response() -> None:
+ """The Pydantic model has to round-trip through JSON because the
+ create-case endpoint embeds ``ticket_refs`` directly into its 201
+ response body. ``model_dump_json`` is the smoke test for that."""
+ cid = uuid.uuid4()
+ r = FanoutResult(
+ connector_id=cid,
+ connector_type="jira",
+ connector_name="Jira (Prod)",
+ status="ok",
+ external_id="AIS-1",
+ external_url="https://example/browse/AIS-1",
+ external_status="To Do",
+ )
+ payload = r.model_dump_json()
+ assert str(cid) in payload
+ assert "AIS-1" in payload
+ assert "\"status\":\"ok\"" in payload
diff --git a/services/api/tests/test_inbox_itsm_endpoint.py b/services/api/tests/test_inbox_itsm_endpoint.py
new file mode 100644
index 000000000..f341666e2
--- /dev/null
+++ b/services/api/tests/test_inbox_itsm_endpoint.py
@@ -0,0 +1,1180 @@
+"""Unit tests for the inbound ITSM webhook (Workstream 8).
+
+The webhook at ``POST /api/v1/inbox/itsm/{tenant_token}/{connector_instance_id}``
+is the *inbound* counterpart to ``case_fanout``. Vendor systems (Jira,
+ServiceNow) hit it when a ticket transitions, and we mirror the new
+status onto ``aisoc_cases``.
+
+Like ``test_lake_endpoint.py`` we keep the assertions on the small
+helpers that own the meaningful behaviour, and exercise the endpoint
+itself via mocked DB sessions instead of spinning up the FastAPI app
++ Postgres harness:
+
+* ``_verify_hmac`` — constant-time HMAC verification with both
+ ``sha256=<hex>`` and bare ``<hex>`` styles. The auth model collapses
+ to "URL token only" when no secret is configured, which is its own
+ branch.
+* ``_parse_jira_payload`` — defensive extraction of ``issue.key`` and
+ ``issue.fields.status.name`` from a Jira webhook. Real-world payloads
+ routinely omit fields we'd otherwise crash on.
+* ``_parse_servicenow_payload`` — accepts both the canonical ``incident``
+ shape and the ``{"current": {...}}`` wrapper that ServiceNow Business
+ Rules emit when the operator forwards ``current`` directly.
+* ``_map_inbound_status`` — vendor → AiSOC enum, intentionally lossy.
+ Anything we can't map returns None and the caller treats that as
+ "no status change".
+* ``inbound_itsm_webhook`` — happy path, HMAC enforcement, JSON parse
+ failures, unknown external IDs, idempotent redelivery, and the
+ vendor-specific dispatch. Mocks ``DBSession`` directly because the
+ endpoint is mostly orchestration and the SQL strings are already
+ covered by the migration tests.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac as _hmac
+import json
+import uuid
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from app.api.v1.endpoints.inbox_itsm import (
+ _ITSM_TEMPLATE_ID,
+ InboundResult,
+ _apply_status_to_case,
+ _fetch_token_and_connector,
+ _map_inbound_status,
+ _parse_jira_payload,
+ _parse_servicenow_payload,
+ _verify_hmac,
+ inbound_itsm_webhook,
+)
+from fastapi import HTTPException
+
+
+# ---------------------------------------------------------------------------
+# _verify_hmac — auth glue. The biggest single attack surface for the
+# whole module: a bug here is "anyone can set any case status", so the
+# test list is intentionally adversarial.
+# ---------------------------------------------------------------------------
+
+
+def _expected_sig(secret: str, body: bytes) -> str:
+ return _hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+
+
+def test_verify_hmac_no_secret_is_noop() -> None:
+ """Tokens minted without an HMAC secret authenticate via URL only.
+
+ This is the correct behaviour for ServiceNow installs that don't
+ expose the BR-side signing knob. We MUST NOT raise here — doing so
+ would brick the most common webhook configuration.
+ """
+ _verify_hmac(secret=None, raw_body=b"anything", signature_header=None)
+ _verify_hmac(secret=None, raw_body=b"anything", signature_header="sha256=garbage")
+
+
+def test_verify_hmac_missing_signature_when_secret_set_raises_401() -> None:
+ """A configured secret demands a signature; the absence is auth failure."""
+ with pytest.raises(HTTPException) as exc:
+ _verify_hmac(secret="topsecret", raw_body=b"{}", signature_header=None)
+ assert exc.value.status_code == 401
+ assert "HMAC signature required" in exc.value.detail
+
+
+def test_verify_hmac_blank_signature_when_secret_set_raises_401() -> None:
+ """An all-whitespace header is treated as missing.
+
+ Vendors occasionally emit ``X-AiSOC-Signature: `` when their secret
+ isn't templated correctly. We refuse it explicitly so the operator
+ notices.
+ """
+ with pytest.raises(HTTPException):
+ _verify_hmac(secret="topsecret", raw_body=b"{}", signature_header=" ")
+
+
+def test_verify_hmac_accepts_sha256_prefixed_signature() -> None:
+ """GitHub-style ``sha256=<hex>`` matches a hex digest."""
+ body = b'{"hello":"world"}'
+ sig = f"sha256={_expected_sig('seekret', body)}"
+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)
+
+
+def test_verify_hmac_accepts_bare_hex_signature() -> None:
+ """ServiceNow / bespoke proxies post bare hex without a prefix."""
+ body = b'{"sys_id":"abc"}'
+ sig = _expected_sig("seekret", body)
+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)
+
+
+def test_verify_hmac_signature_mismatch_raises_401() -> None:
+ """Tampered body invalidates the signature."""
+ sig = _expected_sig("seekret", b"original")
+ with pytest.raises(HTTPException) as exc:
+ _verify_hmac(secret="seekret", raw_body=b"tampered", signature_header=sig)
+ assert exc.value.status_code == 401
+ assert "Invalid HMAC" in exc.value.detail
+
+
+def test_verify_hmac_wrong_secret_raises_401() -> None:
+ """A signature computed with a different secret must not pass.
+
+ Defends against operator copy-paste error (rotated the inbox token
+ secret server-side but forgot to update the vendor side).
+ """
+ body = b'{"a":1}'
+ sig = f"sha256={_expected_sig('wrong-secret', body)}"
+ with pytest.raises(HTTPException):
+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)
+
+
+def test_verify_hmac_case_insensitive_hex_match() -> None:
+ """Some vendors uppercase the hex digest. We accept either case."""
+ body = b'{"foo":"bar"}'
+ sig = _expected_sig("seekret", body).upper()
+ _verify_hmac(secret="seekret", raw_body=body, signature_header=sig)
+
+
+# ---------------------------------------------------------------------------
+# _parse_jira_payload
+# ---------------------------------------------------------------------------
+
+
+def test_parse_jira_payload_happy_path() -> None:
+ """Standard ``jira:issue_updated`` shape extracts issue key + status name."""
+ payload: dict[str, Any] = {
+ "webhookEvent": "jira:issue_updated",
+ "issue": {
+ "key": "AIS-1234",
+ "fields": {"status": {"name": "In Progress"}},
+ },
+ }
+ assert _parse_jira_payload(payload) == ("AIS-1234", "In Progress")
+
+
+def test_parse_jira_payload_missing_issue_returns_none_pair() -> None:
+ """Heartbeat / synthetic payloads skip the writes entirely."""
+ assert _parse_jira_payload({"webhookEvent": "ping"}) == (None, None)
+
+
+def test_parse_jira_payload_issue_not_dict_returns_none_pair() -> None:
+ """Defensive: don't crash if Jira ever ships ``issue: null``."""
+ assert _parse_jira_payload({"issue": None}) == (None, None)
+ assert _parse_jira_payload({"issue": "AIS-1"}) == (None, None)
+
+
+def test_parse_jira_payload_missing_key_returns_none_pair() -> None:
+ """Empty issue.key means nothing to correlate."""
+ assert _parse_jira_payload({"issue": {"key": ""}}) == (None, None)
+
+
+def test_parse_jira_payload_missing_status_keeps_key() -> None:
+ """A renamed-issue webhook has no status; we still return the key.
+
+ The endpoint then treats ``raw_status=None`` as "no transition" and
+ short-circuits. We need the key to bump ``last_synced_at`` even
+ when the actual status didn't change.
+ """
+ payload = {"issue": {"key": "AIS-7", "fields": {}}}
+ assert _parse_jira_payload(payload) == ("AIS-7", None)
+
+
+def test_parse_jira_payload_status_not_dict_keeps_key() -> None:
+ """``fields.status`` may be a string in odd custom workflows; ignore."""
+ payload = {"issue": {"key": "AIS-7", "fields": {"status": "Done"}}}
+ assert _parse_jira_payload(payload) == ("AIS-7", None)
+
+
+def test_parse_jira_payload_fields_not_dict_keeps_key() -> None:
+ """Defensive against Jira's ``fields: null`` on bare-bones webhooks."""
+ payload = {"issue": {"key": "AIS-9", "fields": None}}
+ assert _parse_jira_payload(payload) == ("AIS-9", None)
+
+
+# ---------------------------------------------------------------------------
+# _parse_servicenow_payload
+# ---------------------------------------------------------------------------
+
+
+def test_parse_servicenow_payload_canonical_shape() -> None:
+ """REST-Table-API-shaped payload (top-level fields)."""
+ payload = {"sys_id": "abc123", "state": "6", "short_description": "boom"}
+ assert _parse_servicenow_payload(payload) == ("abc123", "6")
+
+
+def test_parse_servicenow_payload_current_wrapper_shape() -> None:
+ """Business Rule forwarding wraps the GlideRecord in ``current``.
+
+ The two shapes look almost identical and operators routinely ship
+ one when they meant the other. We accept both.
+ """
+ payload = {"current": {"sys_id": "abc123", "state": "7"}}
+ assert _parse_servicenow_payload(payload) == ("abc123", "7")
+
+
+def test_parse_servicenow_payload_state_int_normalised_to_string() -> None:
+ """ServiceNow's ``state`` is numeric in some payloads; we string-ify."""
+ payload = {"sys_id": "abc", "state": 6}
+ assert _parse_servicenow_payload(payload) == ("abc", "6")
+
+
+def test_parse_servicenow_payload_missing_sys_id_returns_none_pair() -> None:
+ """sys_id is the correlation key — without it we can't find the case."""
+ assert _parse_servicenow_payload({"state": 6}) == (None, None)
+
+
+def test_parse_servicenow_payload_empty_sys_id_returns_none_pair() -> None:
+ """Defensive against BRs that emit ``sys_id: ""`` on creation."""
+ assert _parse_servicenow_payload({"sys_id": "", "state": "1"}) == (None, None)
+
+
+def test_parse_servicenow_payload_missing_state_keeps_sys_id() -> None:
+ """An assignment-only webhook has no state change. Same logic as Jira."""
+ assert _parse_servicenow_payload({"sys_id": "abc"}) == ("abc", None)
+
+
+def test_parse_servicenow_payload_current_not_dict_returns_none_pair() -> None:
+ """Defensive: ``current: null`` happens on initial deploy."""
+ assert _parse_servicenow_payload({"current": None}) == (None, None)
+
+
+# ---------------------------------------------------------------------------
+# _map_inbound_status — the canonicalisation table. We assert the
+# specific mappings because they're load-bearing for case workflow:
+# a wrong row here means an operator's "Done" silently doesn't close
+# the case.
+# ---------------------------------------------------------------------------
+
+
+ "raw_status,expected",
+ [
+ # Common Jira flows
+ ("To Do", "triaged"),
+ ("Open", "triaged"),
+ ("Backlog", "triaged"),
+ ("In Progress", "investigating"),
+ ("In Review", "investigating"),
+ ("Blocked", "contained"),
+ ("On Hold", "contained"),
+ ("Resolved", "resolved"),
+ ("Done", "resolved"),
+ ("Closed", "closed"),
+ ("Cancelled", "closed"),
+ ("Won't Fix", "closed"),
+ # Case insensitive — Jira emits status.name as-configured by the
+ # admin, which often lowercases.
+ ("done", "resolved"),
+ ("DONE", "resolved"),
+ # American spelling collapses too.
+ ("Canceled", "closed"),
+ ],
+)
+def test_map_inbound_status_jira_known_states(raw_status: str, expected: str) -> None:
+ assert _map_inbound_status("jira", raw_status) == expected
+
+
+def test_map_inbound_status_jira_unknown_returns_none() -> None:
+ """Unmapped Jira statuses are a no-op, not an error."""
+ assert _map_inbound_status("jira", "Awaiting Customer") is None
+
+
+ "raw_status,expected",
+ [
+ ("1", "triaged"),
+ ("2", "investigating"),
+ ("3", "contained"),
+ ("6", "resolved"),
+ ("7", "closed"),
+ ("8", "closed"),
+ ],
+)
+def test_map_inbound_status_servicenow_known_states(raw_status: str, expected: str) -> None:
+ assert _map_inbound_status("servicenow", raw_status) == expected
+
+
+def test_map_inbound_status_servicenow_unknown_returns_none() -> None:
+ """ServiceNow custom states (e.g. 100, 200) are skipped."""
+ assert _map_inbound_status("servicenow", "100") is None
+
+
+def test_map_inbound_status_unknown_vendor_returns_none() -> None:
+ """A bug in the dispatch shouldn't accidentally close cases."""
+ assert _map_inbound_status("pagerduty", "resolved") is None
+
+
+def test_map_inbound_status_none_status_returns_none() -> None:
+ """Idempotent: ``None`` in, ``None`` out."""
+ assert _map_inbound_status("jira", None) is None
+
+
+# ---------------------------------------------------------------------------
+# _fetch_token_and_connector — auth + tenancy boundary. Every branch
+# here is a 401/403/404/409 — i.e. potential cross-tenant or
+# unauthorised access — so the coverage list is the threat model.
+#
+# The DB is mocked because we're testing the resolution logic, not
+# Postgres semantics. The actual SQL is covered by the integration
+# tests that exercise migration 035.
+# ---------------------------------------------------------------------------
+
+
+def _mock_db(token_row: Any | None, connector_row: Any | None) -> AsyncMock:
+ """Build an AsyncMock DB whose two ``execute`` calls return the
+ rows we want.
+
+ The real endpoint runs the token query first, then the connector
+ query, so we drive the mock with a ``side_effect`` queue.
+ """
+ db = MagicMock()
+ token_result = MagicMock()
+ token_result.fetchone = MagicMock(return_value=token_row)
+ connector_result = MagicMock()
+ connector_result.fetchone = MagicMock(return_value=connector_row)
+ db.execute = AsyncMock(side_effect=[token_result, connector_result])
+ return db
+
+
+async def test_fetch_token_and_connector_happy_path() -> None:
+ """Valid token + matching tenant + supported vendor returns both rows."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="tok-xyz",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ db = _mock_db(token_row, connector_row)
+ tok, conn = await _fetch_token_and_connector(
+ db, tenant_token="tok-xyz", connector_instance_id=connector_id
+ )
+ assert tok is token_row
+ assert conn is connector_row
+
+
+async def test_fetch_token_and_connector_missing_token_raises_401() -> None:
+ """Revoked / never-existed tokens are auth failures."""
+ db = _mock_db(token_row=None, connector_row=None)
+ with pytest.raises(HTTPException) as exc:
+ await _fetch_token_and_connector(
+ db, tenant_token="tok-revoked", connector_instance_id=uuid.uuid4()
+ )
+ assert exc.value.status_code == 401
+ # Don't echo the full token in the error — leakage minimisation.
+ assert "tok-revoked" not in str(exc.value.detail)
+
+
+async def test_fetch_token_and_connector_wrong_template_raises_403() -> None:
+ """Token minted for a different template (e.g. PagerDuty) is rejected.
+
+ Critical for blast-radius limiting: a leaked PagerDuty inbox token
+ must NOT be re-purposable as an ITSM webhook authenticator.
+ """
+ tenant_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="tok-pagerduty",
+ tenant_id=tenant_id,
+ template_id="pagerduty-events",
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ db = _mock_db(token_row, None)
+ with pytest.raises(HTTPException) as exc:
+ await _fetch_token_and_connector(
+ db, tenant_token="tok-pagerduty", connector_instance_id=uuid.uuid4()
+ )
+ assert exc.value.status_code == 403
+ assert "itsm-inbound" in exc.value.detail
+
+
+async def test_fetch_token_and_connector_missing_connector_raises_404() -> None:
+ """Connector deleted but the vendor still pings the old webhook URL."""
+ tenant_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="tok-xyz",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ db = _mock_db(token_row, connector_row=None)
+ with pytest.raises(HTTPException) as exc:
+ await _fetch_token_and_connector(
+ db, tenant_token="tok-xyz", connector_instance_id=uuid.uuid4()
+ )
+ assert exc.value.status_code == 404
+
+
+async def test_fetch_token_and_connector_cross_tenant_raises_403() -> None:
+ """Token from tenant A paired with connector from tenant B is forbidden.
+
+ This is the most important test in the file from a security
+ posture standpoint — a missing tenant check here would let any
+ tenant project status onto any other tenant's cases.
+ """
+ token_row = SimpleNamespace(
+ token="tok-xyz",
+ tenant_id=uuid.uuid4(), # tenant A
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ tenant_id=uuid.uuid4(), # tenant B — different
+ connector_type="jira",
+ enabled=True,
+ )
+ db = _mock_db(token_row, connector_row)
+ with pytest.raises(HTTPException) as exc:
+ await _fetch_token_and_connector(
+ db, tenant_token="tok-xyz", connector_instance_id=connector_row.id
+ )
+ assert exc.value.status_code == 403
+ assert "different tenants" in exc.value.detail
+
+
+async def test_fetch_token_and_connector_disabled_connector_raises_409() -> None:
+ """Disabled connector = ops intentionally paused this integration.
+
+ 409 (not 200) so the vendor's webhook delivery dashboard surfaces
+ the issue and the operator notices, instead of events silently
+ dropping into the void.
+ """
+ tenant_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="tok-xyz",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=False,
+ )
+ db = _mock_db(token_row, connector_row)
+ with pytest.raises(HTTPException) as exc:
+ await _fetch_token_and_connector(
+ db, tenant_token="tok-xyz", connector_instance_id=connector_row.id
+ )
+ assert exc.value.status_code == 409
+
+
+async def test_fetch_token_and_connector_unsupported_vendor_raises_422() -> None:
+ """Splunk-typed connector pointed at the ITSM URL is a config error."""
+ tenant_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="tok-xyz",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ tenant_id=tenant_id,
+ connector_type="splunk",
+ enabled=True,
+ )
+ db = _mock_db(token_row, connector_row)
+ with pytest.raises(HTTPException) as exc:
+ await _fetch_token_and_connector(
+ db, tenant_token="tok-xyz", connector_instance_id=connector_row.id
+ )
+ assert exc.value.status_code == 422
+ assert "splunk" in exc.value.detail
+
+
+# ---------------------------------------------------------------------------
+# _apply_status_to_case — the writes that actually mutate AiSOC state.
+#
+# We verify the SHAPE of the writes (correct table + bound parameters)
+# rather than running them against a real DB. The migration tests are
+# the right place to exercise the SQL itself; here we want to know
+# the endpoint hands the right values to the right tables in the right
+# order.
+# ---------------------------------------------------------------------------
+
+
+async def test_apply_status_to_case_writes_three_rows() -> None:
+ """Three writes per status change: case, ref, system comment.
+
+ Order matters: case row first (the source of truth for status),
+ then the ref (so the NEXT outbound push short-circuits), then the
+ audit comment (read-only, can fail-but-shouldn't but isn't on the
+ hot path). The transaction is committed by the caller — this fn
+ must NOT call ``db.commit``.
+ """
+ db = MagicMock()
+ db.execute = AsyncMock()
+ # Explicitly attach commit/rollback as AsyncMock so we can assert
+ # _apply_status_to_case does NOT call them. Without this, MagicMock
+ # auto-creates attributes on access and ``hasattr`` is always True.
+ db.commit = AsyncMock()
+ db.rollback = AsyncMock()
+
+ case_id = uuid.uuid4()
+ case_row = SimpleNamespace(id=case_id)
+
+ await _apply_status_to_case(
+ db,
+ case_row=case_row,
+ new_status="resolved",
+ actor_label="jira-webhook",
+ external_id="AIS-42",
+ vendor="jira",
+ )
+
+ # Three writes — case, ref, comment.
+ assert db.execute.await_count == 3
+ # Transaction lifecycle is the caller's responsibility (the endpoint),
+ # not this helper's. The helper must stay pure-write so callers can
+ # batch it with other writes inside one transaction.
+ assert db.commit.await_count == 0
+ assert db.rollback.await_count == 0
+
+
+async def test_apply_status_to_case_resolved_sets_resolved_at() -> None:
+ """The ``resolved`` transition stamps resolved_at via COALESCE.
+
+ We assert the SQL string contains ``resolved_at`` because that's
+ the contract with the timeline view. ``closed_at`` must NOT appear
+ on a 'resolved' transition (preventing it from being prematurely
+ set, which would break SLA reporting).
+ """
+ db = MagicMock()
+ db.execute = AsyncMock()
+ case_row = SimpleNamespace(id=uuid.uuid4())
+
+ await _apply_status_to_case(
+ db,
+ case_row=case_row,
+ new_status="resolved",
+ actor_label="jira-webhook",
+ external_id="AIS-42",
+ vendor="jira",
+ )
+
+ # First call is the aisoc_cases UPDATE — verify the dynamic columns.
+ update_sql = str(db.execute.await_args_list[0].args[0])
+ assert "resolved_at" in update_sql
+ assert "closed_at" not in update_sql
+ assert "triaged_at" in update_sql # transitive: resolved implies triaged
+
+
+async def test_apply_status_to_case_closed_sets_closed_at() -> None:
+ """The ``closed`` transition stamps closed_at."""
+ db = MagicMock()
+ db.execute = AsyncMock()
+ case_row = SimpleNamespace(id=uuid.uuid4())
+
+ await _apply_status_to_case(
+ db,
+ case_row=case_row,
+ new_status="closed",
+ actor_label="snow-webhook",
+ external_id="abc-sys-id",
+ vendor="servicenow",
+ )
+
+ update_sql = str(db.execute.await_args_list[0].args[0])
+ assert "closed_at" in update_sql
+
+
+async def test_apply_status_to_case_triaged_does_not_stamp_resolved_or_closed() -> None:
+ """Triage transitions only stamp triaged_at, not later milestones."""
+ db = MagicMock()
+ db.execute = AsyncMock()
+ case_row = SimpleNamespace(id=uuid.uuid4())
+
+ await _apply_status_to_case(
+ db,
+ case_row=case_row,
+ new_status="triaged",
+ actor_label="jira-webhook",
+ external_id="AIS-1",
+ vendor="jira",
+ )
+
+ update_sql = str(db.execute.await_args_list[0].args[0])
+ assert "triaged_at" in update_sql
+ assert "resolved_at" not in update_sql
+ assert "closed_at" not in update_sql
+
+
+def _bind_params(clause: Any) -> dict[str, Any]:
+ """Extract bound parameter values from a SQLAlchemy ``TextClause``.
+
+ SQLAlchemy 2.x doesn't expose a stable public accessor for
+ ``text(...).bindparams(...)`` values, but ``_bindparams`` is the
+ canonical storage on TextClause and has been stable across the
+ 1.4 → 2.x migration. We prefer it over ``compile().params`` because
+ ``compile()`` requires a dialect and silently rewrites our :name
+ parameters into ``%s`` style on a default Postgres dialect.
+ """
+ return {name: bp.value for name, bp in clause._bindparams.items()}
+
+
+async def test_apply_status_to_case_writes_system_comment_with_provenance() -> None:
+ """The audit comment names the vendor + external_id for the timeline."""
+ db = MagicMock()
+ db.execute = AsyncMock()
+ case_row = SimpleNamespace(id=uuid.uuid4())
+
+ await _apply_status_to_case(
+ db,
+ case_row=case_row,
+ new_status="resolved",
+ actor_label="jira-webhook",
+ external_id="AIS-9000",
+ vendor="jira",
+ )
+
+ # Third call is the comment INSERT.
+ comment_call = db.execute.await_args_list[2]
+ bound = _bind_params(comment_call.args[0])
+ assert bound["body"] is not None
+ assert "AIS-9000" in bound["body"]
+ assert "Jira" in bound["body"]
+ assert "resolved" in bound["body"]
+ assert bound["author"] == "jira-webhook"
+
+
+# ---------------------------------------------------------------------------
+# inbound_itsm_webhook — endpoint orchestration. We mock _fetch_token,
+# _apply_status, and the DB so we can assert the dispatch logic
+# (vendor → parser, parsed status → mapper, mapped status → write or
+# no-op) without spinning the FastAPI app up.
+# ---------------------------------------------------------------------------
+
+
+def _build_request(body: bytes) -> MagicMock:
+ """Build a Request-like mock whose ``body()`` returns ``body``."""
+ req = MagicMock()
+ req.body = AsyncMock(return_value=body)
+ return req
+
+
+def _build_db_for_endpoint(
+ *,
+ token_row: Any,
+ connector_row: Any,
+ ref_row: Any | None,
+ case_already_in_target_status: bool = False,
+) -> MagicMock:
+ """Build a MagicMock DB whose execute() chain covers the endpoint flow.
+
+ Order of execute() calls in the endpoint when we get past auth:
+ 1. SELECT token row
+ 2. SELECT connector row
+ 3. SELECT case_external_refs JOIN aisoc_cases (the 'ref_row' here)
+ 4. UPDATE tenant_inbox_tokens.last_used_at
+ 5..N. _apply_status_to_case writes (when status actually changes)
+ OR UPDATE last_synced_at on case_external_refs (when it doesn't)
+
+ We just queue enough MagicMock results to cover the longest path.
+ """
+ results = []
+ # Token + connector
+ for row in (token_row, connector_row):
+ r = MagicMock()
+ r.fetchone = MagicMock(return_value=row)
+ results.append(r)
+ # case_external_refs JOIN
+ r = MagicMock()
+ r.fetchone = MagicMock(return_value=ref_row)
+ results.append(r)
+ # last_used_at update + any subsequent UPDATEs all just return a
+ # noop result; we don't .fetchone() on them.
+ for _ in range(8):
+ results.append(MagicMock())
+
+ db = MagicMock()
+ db.execute = AsyncMock(side_effect=results)
+ # The endpoint commits at the end of the happy path and rolls back on
+ # exception — both must be awaitable on this mock.
+ db.commit = AsyncMock()
+ db.rollback = AsyncMock()
+ return db
+
+
+async def test_endpoint_invalid_json_raises_400() -> None:
+ """Garbage body → 400 Bad Request, not a 500."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ db = _build_db_for_endpoint(token_row=token_row, connector_row=connector_row, ref_row=None)
+ request = _build_request(b"this is not json")
+
+ with pytest.raises(HTTPException) as exc:
+ await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+ assert exc.value.status_code == 400
+ assert "not valid JSON" in exc.value.detail
+
+
+async def test_endpoint_non_object_json_raises_400() -> None:
+ """``[1,2,3]`` is valid JSON but we need an object."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ db = _build_db_for_endpoint(token_row=token_row, connector_row=connector_row, ref_row=None)
+ request = _build_request(b"[1,2,3]")
+
+ with pytest.raises(HTTPException) as exc:
+ await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+ assert exc.value.status_code == 400
+
+
+async def test_endpoint_missing_external_id_returns_200_with_note() -> None:
+ """Heartbeat / malformed-payload Jira webhooks 200 with status_changed=False."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ db = _build_db_for_endpoint(token_row=token_row, connector_row=connector_row, ref_row=None)
+ request = _build_request(json.dumps({"webhookEvent": "ping"}).encode())
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+
+ assert isinstance(result, InboundResult)
+ assert result.status_changed is False
+ assert result.case_id is None
+ assert result.external_id is None
+ assert result.note is not None
+ assert "missing required fields" in result.note
+
+
+async def test_endpoint_unlinked_external_id_returns_200_with_note() -> None:
+ """ITSM ticket exists but isn't linked to any AiSOC case → soft-200."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ # ref_row=None means the JOIN found no AiSOC link.
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=None
+ )
+ body = json.dumps(
+ {
+ "issue": {
+ "key": "AIS-99",
+ "fields": {"status": {"name": "Done"}},
+ }
+ }
+ ).encode()
+ request = _build_request(body)
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+
+ assert result.status_changed is False
+ assert result.case_id is None
+ assert result.external_id == "AIS-99"
+ assert "AIS-99" in (result.note or "")
+
+
+async def test_endpoint_idempotent_when_case_already_in_target_status() -> None:
+ """Re-delivered "Done" event when case is already 'resolved' → no rewrite.
+
+ The vendor will hammer this URL on every retry, so the most common
+ real-world execution is a redelivery. We must:
+ * still 200 OK (so the vendor stops retrying),
+ * still bump last_synced_at (so the operator knows the token is alive),
+ * NOT rewrite ``aisoc_cases.status`` (no-op DB load),
+ * NOT post a duplicate "Jira ticket transitioned" system comment
+ (would spam the timeline view).
+ """
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ case_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ ref_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ case_id=case_id,
+ external_status="resolved",
+ aisoc_case_id=case_id,
+ case_number="CASE-1",
+ status="resolved", # already in the target state
+ )
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=ref_row
+ )
+ body = json.dumps(
+ {"issue": {"key": "AIS-1", "fields": {"status": {"name": "Done"}}}}
+ ).encode()
+ request = _build_request(body)
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+
+ assert result.status_changed is False
+ assert result.old_status == "resolved"
+ assert result.new_status == "resolved"
+ assert result.case_id == case_id
+ assert result.case_number == "CASE-1"
+
+
+async def test_endpoint_unmapped_status_bumps_last_synced_only() -> None:
+ """Vendor status that doesn't map to AiSOC → ``status_changed=False``.
+
+ Operators occasionally configure custom Jira workflows with statuses
+ we've never heard of ("Awaiting Customer", "Released to QA"). The
+ contract: never lose data, never crash, always 200.
+ """
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ case_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ ref_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ case_id=case_id,
+ external_status="investigating",
+ aisoc_case_id=case_id,
+ case_number="CASE-2",
+ status="investigating",
+ )
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=ref_row
+ )
+ body = json.dumps(
+ {
+ "issue": {
+ "key": "AIS-2",
+ "fields": {"status": {"name": "Awaiting Customer"}},
+ }
+ }
+ ).encode()
+ request = _build_request(body)
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+
+ assert result.status_changed is False
+ assert result.old_status == "investigating"
+ assert result.new_status == "investigating"
+ assert "Awaiting Customer" in (result.note or "")
+
+
+async def test_endpoint_real_status_change_writes_and_returns_changed() -> None:
+ """Vendor 'Done' → AiSOC 'resolved' mirrors the status onto the case."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ case_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ ref_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ case_id=case_id,
+ external_status="investigating",
+ aisoc_case_id=case_id,
+ case_number="CASE-7",
+ status="investigating",
+ )
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=ref_row
+ )
+ body = json.dumps(
+ {"issue": {"key": "AIS-7", "fields": {"status": {"name": "Done"}}}}
+ ).encode()
+ request = _build_request(body)
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+
+ assert result.status_changed is True
+ assert result.old_status == "investigating"
+ assert result.new_status == "resolved"
+ assert result.case_id == case_id
+ assert result.case_number == "CASE-7"
+ assert result.external_id == "AIS-7"
+
+
+async def test_endpoint_servicenow_dispatches_to_servicenow_parser() -> None:
+ """A ServiceNow connector type routes through ``_parse_servicenow_payload``.
+
+ Numeric state ``"6"`` → ``"resolved"`` confirms both the dispatch
+ and the SNow-specific mapping.
+ """
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ case_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret=None,
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="servicenow",
+ enabled=True,
+ )
+ ref_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ case_id=case_id,
+ external_status="investigating",
+ aisoc_case_id=case_id,
+ case_number="CASE-9",
+ status="investigating",
+ )
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=ref_row
+ )
+ body = json.dumps({"sys_id": "abc-1", "state": 6}).encode()
+ request = _build_request(body)
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None,
+ )
+
+ assert result.status_changed is True
+ assert result.new_status == "resolved"
+ assert result.external_id == "abc-1"
+
+
+async def test_endpoint_hmac_required_but_missing_returns_401() -> None:
+ """Token has hmac_secret but request omits the signature → 401.
+
+ Verifies HMAC is enforced on the *real* endpoint, not just on
+ ``_verify_hmac`` in isolation. The order of operations matters:
+ HMAC must run *before* JSON parsing so a forged-but-valid-JSON
+ body can't trigger any DB reads.
+ """
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret="seekret", # configured
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=None
+ )
+ request = _build_request(b"{}")
+
+ with pytest.raises(HTTPException) as exc:
+ await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=None, # missing
+ )
+ assert exc.value.status_code == 401
+
+
+async def test_endpoint_hmac_valid_passes_through() -> None:
+ """A correctly signed request authenticates and proceeds normally."""
+ tenant_id = uuid.uuid4()
+ connector_id = uuid.uuid4()
+ case_id = uuid.uuid4()
+ token_row = SimpleNamespace(
+ token="t",
+ tenant_id=tenant_id,
+ template_id=_ITSM_TEMPLATE_ID,
+ hmac_secret="seekret",
+ revoked_at=None,
+ )
+ connector_row = SimpleNamespace(
+ id=connector_id,
+ tenant_id=tenant_id,
+ connector_type="jira",
+ enabled=True,
+ )
+ ref_row = SimpleNamespace(
+ id=uuid.uuid4(),
+ case_id=case_id,
+ external_status="investigating",
+ aisoc_case_id=case_id,
+ case_number="CASE-5",
+ status="investigating",
+ )
+ db = _build_db_for_endpoint(
+ token_row=token_row, connector_row=connector_row, ref_row=ref_row
+ )
+ body = json.dumps(
+ {"issue": {"key": "AIS-5", "fields": {"status": {"name": "Done"}}}}
+ ).encode()
+ sig = f"sha256={_expected_sig('seekret', body)}"
+ request = _build_request(body)
+
+ result = await inbound_itsm_webhook(
+ tenant_token="t",
+ connector_instance_id=connector_id,
+ request=request,
+ db=db,
+ x_aisoc_signature=sig,
+ )
+
+ assert result.status_changed is True
+ assert result.new_status == "resolved"
diff --git a/services/connectors/tests/test_push_capabilities.py b/services/connectors/tests/test_push_capabilities.py
new file mode 100644
index 000000000..429b5e901
--- /dev/null
+++ b/services/connectors/tests/test_push_capabilities.py
@@ -0,0 +1,730 @@
+"""Unit tests for Workstream 8 ``push_case`` / ``push_status_change`` paths.
+
+These tests cover the bidirectional ITSM capability shipped on the Jira and
+ServiceNow connectors:
+
+* ``push_case`` happy paths (correct payload, correct vendor mapping) and the
+ HTTP error → ``HTTPStatusError`` propagation contract the fan-out service
+ depends on.
+* ``push_status_change`` decision tree:
+ - ``external_ref is None`` → falls through to ``push_case`` so callers
+ don't have to special-case "first push".
+ - Unknown AiSOC status → no-op return (no HTTP call) since the contract
+ is "best-effort projection", not "schema match".
+ - Jira: discover-then-transition path including the "no transition
+ available for target status" workflow no-op.
+ - ServiceNow: ``Resolved`` / ``Closed`` states require ``close_code`` +
+ ``close_notes`` or the API silently ignores the state change.
+
+We deliberately avoid ``respx`` (not installed in this env per
+``pyproject.toml`` dev deps) and instead patch ``httpx.AsyncClient`` with
+``unittest.mock`` mirroring ``services/api/tests/test_case_fanout.py``. That
+also keeps these tests aligned with the in-repo mock patterns reviewers
+already understand.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+from app.connectors.jira_connector import JiraConnector
+from app.connectors.servicenow import ServiceNowConnector
+
+
+# ---------------------------------------------------------------------------
+# Helpers — build httpx.Response stubs without instantiating a real Client.
+# ---------------------------------------------------------------------------
+
+
+def _build_response(
+ *,
+ status_code: int = 200,
+ json_body: dict[str, Any] | list[Any] | None = None,
+ text: str = "",
+ method: str = "POST",
+ url: str = "http://example.invalid/",
+) -> MagicMock:
+ """Build a MagicMock that walks like an ``httpx.Response``.
+
+ We only need the attributes the connector code touches:
+ ``status_code``, ``json()``, ``text``, ``request``, plus ``raise_for_status``
+ (called by ``_resolve_transition_id`` on the Jira side).
+ """
+ resp = MagicMock(spec=httpx.Response)
+ resp.status_code = status_code
+ resp.json = MagicMock(return_value=json_body if json_body is not None else {})
+ resp.text = text
+ # ``request`` is required for ``HTTPStatusError`` construction.
+ resp.request = httpx.Request(method, url)
+
+ def _raise_for_status() -> None:
+ if status_code >= 400:
+ raise httpx.HTTPStatusError(
+ f"{status_code} error",
+ request=resp.request,
+ response=resp,
+ )
+
+ resp.raise_for_status = MagicMock(side_effect=_raise_for_status)
+ return resp
+
+
+def _patch_async_client(
+ *,
+ post_responses: list[MagicMock] | MagicMock | None = None,
+ get_responses: list[MagicMock] | MagicMock | None = None,
+ patch_responses: list[MagicMock] | MagicMock | None = None,
+) -> tuple[Any, AsyncMock, AsyncMock, AsyncMock]:
+ """Patch ``httpx.AsyncClient`` for a connector module.
+
+ Returns ``(context_manager, post_mock, get_mock, patch_mock)``. Use as::
+
+ with _patch_async_client(...) as ctx:
+ post_mock, get_mock, patch_mock = ctx
+
+ Or, more commonly here, drive each patch context directly per test.
+ """
+ raise NotImplementedError # placeholder — kept for shape; tests use the inline pattern below.
+
+
+def _async_responses(responses: list[MagicMock] | MagicMock | None) -> AsyncMock:
+ """Build an AsyncMock that returns each response in sequence (or always
+ the same one if a single mock is supplied)."""
+ if responses is None:
+ return AsyncMock(side_effect=AssertionError("unexpected HTTP call"))
+ if isinstance(responses, list):
+ return AsyncMock(side_effect=responses)
+ return AsyncMock(return_value=responses)
+
+
+# ===========================================================================
+# Jira: push_case
+# ===========================================================================
+
+
+async def test_jira_push_case_builds_correct_payload_and_url() -> None:
+ """Happy path: severity → priority, ADF description, aisoc-case label."""
+ case = {
+ "id": "11111111-2222-3333-4444-555555555555",
+ "case_number": "AIS-42",
+ "title": "Suspected lateral movement",
+ "description": "Multiple SMB connects from finance subnet to DC.",
+ "severity": "high",
+ "status": "investigating",
+ }
+
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net/", # trailing slash on purpose.
+ api_token="api-token-xyz",
+ project_key="SEC",
+ )
+ response = _build_response(
+ status_code=201,
+ json_body={"key": "SEC-42", "id": "10042"},
+ )
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ result = await connector.push_case(case)
+
+ assert post_mock.await_count == 1
+ call = post_mock.await_args
+ # ``base_url`` was rstripped, so the resulting URL has exactly one slash.
+ assert call.args[0] == "https://acme.atlassian.net/rest/api/3/issue"
+
+ payload = call.kwargs["json"]
+ assert payload["fields"]["project"] == {"key": "SEC"}
+ assert payload["fields"]["priority"] == {"name": "High"}
+ # ADF doc shape — connector wraps the plain string under content[0].text.
+ assert payload["fields"]["description"]["type"] == "doc"
+ assert (
+ payload["fields"]["description"]["content"][0]["content"][0]["text"]
+ == case["description"]
+ )
+ # Label round-trips the AiSOC case identifier so the inbound webhook
+ # can link the issue back to us without a custom field.
+ assert f"aisoc-case-{case['id']}" in payload["fields"]["labels"]
+ assert "aisoc" in payload["fields"]["labels"]
+
+ headers = call.kwargs["headers"]
+ assert headers["Authorization"].startswith("Basic ")
+
+ assert result == {
+ "external_id": "SEC-42",
+ "external_url": "https://acme.atlassian.net/browse/SEC-42",
+ "vendor": "jira",
+ "external_status": "To Do",
+ }
+
+
+async def test_jira_push_case_requires_project_key() -> None:
+ """Missing project_key MUST raise rather than silently 400 against Jira."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key=None,
+ )
+
+ with pytest.raises(ValueError, match="project_key not configured"):
+ await connector.push_case({"id": "1", "title": "x"})
+
+
+async def test_jira_push_case_severity_collapses_to_default() -> None:
+ """Unknown severity falls back to Medium rather than crashing."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ response = _build_response(
+ status_code=201, json_body={"key": "SEC-1", "id": "1"}
+ )
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ await connector.push_case({"id": "1", "title": "x", "severity": "absurdly-bad"})
+
+ payload = post_mock.await_args.kwargs["json"]
+ assert payload["fields"]["priority"] == {"name": "Medium"}
+
+
+async def test_jira_push_case_summary_truncates_at_255() -> None:
+ """Jira hard-caps summary at 255 chars; longer titles must be sliced."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ long_title = "x" * 400
+ response = _build_response(
+ status_code=201, json_body={"key": "SEC-1", "id": "1"}
+ )
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ await connector.push_case({"id": "1", "title": long_title})
+
+ payload = post_mock.await_args.kwargs["json"]
+ assert len(payload["fields"]["summary"]) == 255
+
+
+async def test_jira_push_case_raises_on_4xx() -> None:
+ """Jira 4xx must surface as HTTPStatusError so the fan-out service can
+ persist a ``failed`` external_ref instead of silently dropping the push."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ response = _build_response(status_code=400, text="bad project key")
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ with pytest.raises(httpx.HTTPStatusError, match="jira.push_case failed"):
+ await connector.push_case({"id": "1", "title": "x"})
+
+
+# ===========================================================================
+# Jira: push_status_change
+# ===========================================================================
+
+
+async def test_jira_push_status_change_falls_through_to_push_case_when_no_ref() -> None:
+ """First-time push (no existing external_ref) must mint the issue."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ response = _build_response(
+ status_code=201, json_body={"key": "SEC-7", "id": "7"}
+ )
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ result = await connector.push_status_change(
+ case={"id": "abc", "title": "lateral", "severity": "low"},
+ old_status="new",
+ new_status="investigating",
+ external_ref=None,
+ )
+
+ # Single POST to /rest/api/3/issue, no transitions discovery.
+ assert post_mock.await_count == 1
+ assert post_mock.await_args.args[0].endswith("/rest/api/3/issue")
+ assert result["external_id"] == "SEC-7"
+
+
+async def test_jira_push_status_change_requires_external_id_in_ref() -> None:
+ """An external_ref dict without ``external_id`` is operator error."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ with pytest.raises(ValueError, match="missing external_id"):
+ await connector.push_status_change(
+ case={"id": "abc"},
+ old_status="new",
+ new_status="resolved",
+ external_ref={"vendor": "jira"}, # no external_id
+ )
+
+
+async def test_jira_push_status_change_unknown_status_is_noop() -> None:
+ """Unknown AiSOC statuses return without making any HTTP call."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ # If we DO end up calling httpx, the context manager's get/post
+ # mocks are AsyncMock() defaults — nothing assertable here, so the
+ # real check is "we never enter the client at all".
+ result = await connector.push_status_change(
+ case={"id": "abc"},
+ old_status="new",
+ new_status="alien-status",
+ external_ref={"external_id": "SEC-9", "external_status": "To Do"},
+ )
+ # Connector must NOT instantiate a client when there's no work.
+ assert mock_client.call_count == 0
+
+ assert result["external_id"] == "SEC-9"
+ assert result["external_status"] == "To Do" # unchanged from external_ref
+
+
+async def test_jira_push_status_change_no_matching_transition_is_noop() -> None:
+ """Workflow may not expose a transition to the target status — return
+ without mutating, since retrying won't change the workflow."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ transitions_response = _build_response(
+ status_code=200,
+ json_body={
+ "transitions": [
+ {"id": "11", "name": "Reopen", "to": {"name": "To Do"}},
+ # No "Done" or "In Progress" transition exposed.
+ ]
+ },
+ )
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ get_mock = AsyncMock(return_value=transitions_response)
+ post_mock = AsyncMock() # MUST NOT be called.
+ mock_client.return_value.__aenter__.return_value.get = get_mock
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+
+ result = await connector.push_status_change(
+ case={"id": "abc"},
+ old_status="new",
+ new_status="resolved", # → "Done", not in workflow.
+ external_ref={"external_id": "SEC-9", "external_status": "To Do"},
+ )
+
+ assert get_mock.await_count == 1
+ assert post_mock.await_count == 0 # critical: no transition POST
+ assert result["external_id"] == "SEC-9"
+
+
+async def test_jira_push_status_change_resolves_and_posts_transition() -> None:
+ """Happy path: discover the transition then POST it with that ID."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ transitions_response = _build_response(
+ status_code=200,
+ json_body={
+ "transitions": [
+ {"id": "11", "name": "Start", "to": {"name": "In Progress"}},
+ {"id": "21", "name": "Resolve", "to": {"name": "Done"}},
+ ]
+ },
+ )
+ transition_post = _build_response(status_code=204)
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ get_mock = AsyncMock(return_value=transitions_response)
+ post_mock = AsyncMock(return_value=transition_post)
+ mock_client.return_value.__aenter__.return_value.get = get_mock
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+
+ result = await connector.push_status_change(
+ case={"id": "abc"},
+ old_status="new",
+ new_status="resolved",
+ external_ref={"external_id": "SEC-9", "external_status": "To Do"},
+ )
+
+ # GET .../transitions then POST .../transitions with id=21.
+ assert get_mock.await_args.args[0].endswith("/rest/api/3/issue/SEC-9/transitions")
+ assert post_mock.await_args.args[0].endswith("/rest/api/3/issue/SEC-9/transitions")
+ assert post_mock.await_args.kwargs["json"] == {"transition": {"id": "21"}}
+ assert result["external_status"] == "Done"
+
+
+async def test_jira_push_status_change_raises_on_transition_4xx() -> None:
+ """A non-2xx on the transition POST surfaces as HTTPStatusError."""
+ connector = JiraConnector(
+ base_url="https://acme.atlassian.net",
+ api_token="t",
+ project_key="SEC",
+ )
+ transitions_response = _build_response(
+ status_code=200,
+ json_body={"transitions": [{"id": "21", "name": "Resolve", "to": {"name": "Done"}}]},
+ )
+ transition_post = _build_response(status_code=403, text="forbidden")
+
+ with patch("app.connectors.jira_connector.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.get = AsyncMock(
+ return_value=transitions_response
+ )
+ mock_client.return_value.__aenter__.return_value.post = AsyncMock(
+ return_value=transition_post
+ )
+
+ with pytest.raises(httpx.HTTPStatusError, match="jira.push_status_change failed"):
+ await connector.push_status_change(
+ case={"id": "abc"},
+ old_status="new",
+ new_status="closed",
+ external_ref={"external_id": "SEC-9"},
+ )
+
+
+# ===========================================================================
+# ServiceNow: push_case
+# ===========================================================================
+
+
+async def test_snow_push_case_posts_to_table_with_correlation_id() -> None:
+ """Happy path: incident table POST, correlation_id round-trips case id."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com/",
+ username="aisoc-bot",
+ password="hunter2",
+ )
+ response = _build_response(
+ status_code=201,
+ json_body={
+ "result": {
+ "sys_id": "abcdef0123456789abcdef0123456789",
+ "number": "INC0010023",
+ "state": "1",
+ }
+ },
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+
+ result = await connector.push_case(
+ {
+ "id": "case-uuid-1",
+ "case_number": "AIS-42",
+ "title": "Lateral movement detected",
+ "description": "SMB scan",
+ "severity": "critical",
+ }
+ )
+
+ assert post_mock.await_count == 1
+ call = post_mock.await_args
+ assert call.args[0] == "https://acme.service-now.com/api/now/table/incident"
+ body = call.kwargs["json"]
+ assert body["short_description"] == "Lateral movement detected"
+ # severity=critical → impact=1 (urgency mirrors impact for OOTB).
+ assert body["impact"] == "1"
+ assert body["urgency"] == "1"
+ # correlation_id round-trips the AiSOC case identifier.
+ assert body["correlation_id"] == "aisoc:case-uuid-1"
+
+ assert result["external_id"] == "abcdef0123456789abcdef0123456789"
+ assert result["vendor"] == "servicenow"
+ # _record_url with number returns the nav_to.do form.
+ assert "sys_id=abcdef0123456789abcdef0123456789" in result["external_url"]
+
+
+async def test_snow_push_case_short_description_truncates_at_160() -> None:
+ """short_description in ServiceNow caps at 160 chars."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(
+ status_code=201, json_body={"result": {"sys_id": "x" * 32, "state": "1"}}
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ await connector.push_case({"id": "1", "title": "y" * 300})
+
+ body = post_mock.await_args.kwargs["json"]
+ assert len(body["short_description"]) == 160
+
+
+async def test_snow_push_case_raises_on_4xx() -> None:
+ """ServiceNow 4xx must propagate so the fan-out service can mark
+ the external_ref ``failed`` rather than silently dropping the push."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(status_code=400, text="ACL denied")
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ with pytest.raises(httpx.HTTPStatusError, match="servicenow.push_case failed"):
+ await connector.push_case({"id": "1", "title": "x"})
+
+
+# ===========================================================================
+# ServiceNow: push_status_change
+# ===========================================================================
+
+
+async def test_snow_push_status_change_falls_through_to_push_case_when_no_ref() -> None:
+ """No ref → mint the incident."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(
+ status_code=201, json_body={"result": {"sys_id": "x" * 32, "state": "1"}}
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ post_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.post = post_mock
+ result = await connector.push_status_change(
+ case={"id": "1", "title": "x"},
+ old_status="new",
+ new_status="investigating",
+ external_ref=None,
+ )
+
+ assert post_mock.await_count == 1
+ assert post_mock.await_args.args[0].endswith("/api/now/table/incident")
+ assert result["external_id"] == "x" * 32
+
+
+async def test_snow_push_status_change_requires_external_id_in_ref() -> None:
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ with pytest.raises(ValueError, match="missing external_id"):
+ await connector.push_status_change(
+ case={"id": "1"},
+ old_status="new",
+ new_status="resolved",
+ external_ref={"vendor": "servicenow"},
+ )
+
+
+async def test_snow_push_status_change_unknown_status_is_noop() -> None:
+ """Unknown AiSOC status → no HTTP call, return ref unchanged."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ result = await connector.push_status_change(
+ case={"id": "1"},
+ old_status="new",
+ new_status="alien-status",
+ external_ref={"external_id": "ABC", "external_status": "1"},
+ )
+ assert mock_client.call_count == 0
+
+ assert result["external_id"] == "ABC"
+ assert result["external_status"] == "1"
+
+
+async def test_snow_push_status_change_in_progress_patches_state_only() -> None:
+ """Non-resolved transitions only set ``state`` — no close metadata."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(
+ status_code=200, json_body={"result": {"sys_id": "abc", "state": "2"}}
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ patch_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.patch = patch_mock
+
+ result = await connector.push_status_change(
+ case={"id": "case-uuid"},
+ old_status="new",
+ new_status="investigating",
+ external_ref={"external_id": "abc", "external_status": "1"},
+ )
+
+ assert patch_mock.await_count == 1
+ body = patch_mock.await_args.kwargs["json"]
+ assert body == {"state": "2"}
+ # Critically: no close_code / close_notes when not Resolved/Closed.
+ assert "close_code" not in body
+ assert "close_notes" not in body
+ assert result["external_status"] == "2"
+
+
+async def test_snow_push_status_change_resolved_includes_close_metadata() -> None:
+ """Resolved/Closed transitions MUST send close_code+close_notes or
+ ServiceNow silently rejects the state change on most stock instances."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(
+ status_code=200, json_body={"result": {"sys_id": "abc", "state": "6"}}
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ patch_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.patch = patch_mock
+
+ await connector.push_status_change(
+ case={"id": "case-uuid", "case_number": "AIS-42"},
+ old_status="investigating",
+ new_status="resolved",
+ external_ref={"external_id": "abc", "external_status": "2"},
+ )
+
+ body = patch_mock.await_args.kwargs["json"]
+ assert body["state"] == "6"
+ assert body["close_code"] # any non-empty default
+ assert "AIS-42" in body["close_notes"]
+
+
+async def test_snow_push_status_change_closed_includes_close_metadata() -> None:
+ """Same contract as Resolved for the Closed (state=7) bucket."""
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(
+ status_code=200, json_body={"result": {"sys_id": "abc", "state": "7"}}
+ )
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ patch_mock = AsyncMock(return_value=response)
+ mock_client.return_value.__aenter__.return_value.patch = patch_mock
+
+ await connector.push_status_change(
+ case={"id": "case-uuid"},
+ old_status="resolved",
+ new_status="closed",
+ external_ref={"external_id": "abc", "external_status": "6"},
+ )
+
+ body = patch_mock.await_args.kwargs["json"]
+ assert body["state"] == "7"
+ assert "close_code" in body
+ assert "close_notes" in body
+
+
+async def test_snow_push_status_change_raises_on_4xx() -> None:
+ connector = ServiceNowConnector(
+ instance_url="https://acme.service-now.com",
+ username="u",
+ password="p",
+ )
+ response = _build_response(status_code=403, text="ACL denied on incident")
+
+ with patch("app.connectors.servicenow.httpx.AsyncClient") as mock_client:
+ mock_client.return_value.__aenter__.return_value.patch = AsyncMock(
+ return_value=response
+ )
+ with pytest.raises(httpx.HTTPStatusError, match="servicenow.push_status_change failed"):
+ await connector.push_status_change(
+ case={"id": "1"},
+ old_status="new",
+ new_status="resolved",
+ external_ref={"external_id": "abc"},
+ )
+
+
+# ===========================================================================
+# Capability declarations — guard against accidental drop in future PRs.
+# ===========================================================================
+
+
+def test_jira_capabilities_advertise_push() -> None:
+ from app.connectors.base import Capability
+
+ caps = JiraConnector.capabilities()
+ assert Capability.PUSH_CASE in caps
+ assert Capability.PUSH_STATUS in caps
+ assert Capability.PULL_ALERTS in caps # pre-WS8 capability still intact
+
+
+def test_servicenow_capabilities_advertise_push() -> None:
+ from app.connectors.base import Capability
+
+ caps = ServiceNowConnector.capabilities()
+ assert Capability.PUSH_CASE in caps
+ assert Capability.PUSH_STATUS in caps
+ assert Capability.PULL_ALERTS in caps