thessor 0.2.0__py3-none-any.whl

thessor/__init__.py

@@ -0,0 +1,26 @@
+from thessor.client import Client
+from thessor.crypto import canonicalize, sha256_hex, hash_patient_id
+from thessor.fhir import FHIRConnector
+from thessor.dicom import DICOMSRConnector
+from thessor.atna import ATNAConnector, ATNAAuditMessage
+from thessor.hl7 import HL7Connector
+from thessor.mcp import ThessorMCPMiddleware
+from thessor.models import SealResult, SealWithRationaleResult, VerifyResult, ChainResult
+from thessor.exceptions import (
+    ThessorError, AuthError, NotFoundError,
+    ValidationError, RateLimitError, ServerError
+)
+
+ThessorClient = Client
+
+__version__ = "0.2.0"
+__all__ = [
+    "Client",
+    "ThessorClient",
+    "FHIRConnector", "DICOMSRConnector", "ATNAConnector", "ATNAAuditMessage", "HL7Connector",
+    "ThessorMCPMiddleware",
+    "SealResult", "SealWithRationaleResult", "VerifyResult", "ChainResult",
+    "canonicalize", "sha256_hex", "hash_patient_id",
+    "ThessorError", "AuthError", "NotFoundError",
+    "ValidationError", "RateLimitError", "ServerError",
+]

thessor/atna.py

@@ -0,0 +1,345 @@
+"""IHE ATNA (Audit Trail and Node Authentication) connector for the Thessor SDK.
+
+Hospitals run ATNA Audit Record Repositories (ARR) today. This connector slots
+directly into that infrastructure: it emits DICOM PS3.15 / RFC 3881 conformant
+AuditMessage XML, ships it to the ARR over UDP or TLS syslog, and then seals
+the message itself through a thessor.Client — making the hospital's own audit
+trail tamper-evident.
+
+Transport is RFC 5424 syslog (UDP) or RFC 5425 syslog (TLS with octet-count
+framing). The message format is AuditMessage XML with a UTF-8 declaration.
+
+Stdlib only — xml.etree.ElementTree, socket, ssl, base64. No third-party
+dependencies.
+"""
+
+import base64
+import socket
+import ssl
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .crypto import sha256_hex
+from .models import SealResult
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# DCM event codes.
+EVENT_APPLICATION_ACTIVITY = "110100"
+EVENT_IMPORT               = "110107"
+EVENT_EXPORT               = "110106"
+EVENT_QUERY                = "110112"
+EVENT_AI_DECISION_SEALED   = "THSR-001"   # Thessor extension code
+
+# Event action codes.
+ACTION_CREATE  = "C"
+ACTION_READ    = "R"
+ACTION_EXECUTE = "E"
+
+# Outcome indicators.
+OUTCOME_SUCCESS         = "0"
+OUTCOME_MINOR_FAILURE   = "4"
+OUTCOME_SERIOUS_FAILURE = "8"
+OUTCOME_MAJOR_FAILURE   = "12"
+
+# Role ID codes.
+ROLE_APPLICATION = "110150"
+ROLE_DESTINATION = "110152"
+ROLE_SOURCE      = "110153"
+
+# Participant object type codes.
+OBJ_TYPE_SYSTEM = "2"
+
+# Participant object type code roles.
+OBJ_ROLE_JOB = "20"
+
+THESSOR_AUDIT_SOURCE_ID = "api.thessor.com"
+THESSOR_CODING_SCHEME   = "THESSOR"
+
+DEFAULT_SYSLOG_PORT_UDP = 514
+DEFAULT_SYSLOG_PORT_TLS = 6514
+
+# RFC 5424 syslog priority: facility=1 (user-level), severity=5 (notice).
+_SYSLOG_PRIORITY = 13
+
+
+# ---------------------------------------------------------------------------
+# ATNAAuditMessage dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ATNAAuditMessage:
+    """A single IHE ATNA audit event, serialisable to DICOM PS3.15 XML."""
+
+    event_id: str                        # DCM code e.g. EVENT_IMPORT
+    event_action: str                    # ACTION_EXECUTE etc.
+    event_datetime: str                  # ISO 8601 UTC
+    event_outcome: str                   # OUTCOME_SUCCESS etc.
+    user_id: str                         # caller identity
+    audit_source_id: str                 # originating system
+    participant_object_id: str           # the sealed object ID (envelope_id)
+    participant_object_details: dict     # str → str extra fields
+    event_type_code: str | None = None
+    event_type_code_scheme: str = "DCM"
+    user_name: str | None = None
+    network_access_point: str | None = None
+
+    # Human-readable labels for the fixed DCM event codes used here.
+    _EVENT_ID_TEXT: dict = field(default_factory=lambda: {
+        EVENT_APPLICATION_ACTIVITY: "Application Activity",
+        EVENT_IMPORT:               "Import",
+        EVENT_EXPORT:               "Export",
+        EVENT_QUERY:                "Query",
+        EVENT_AI_DECISION_SEALED:   "AI Decision Sealed",
+    }, init=False, repr=False, compare=False)
+
+    def to_xml(self) -> str:
+        """Build and return a DICOM PS3.15 AuditMessage XML string.
+
+        ParticipantObjectDetail values are base64-encoded per the ATNA
+        standard. The string is prefixed with an XML 1.0 UTF-8 declaration.
+        """
+        root = ET.Element("AuditMessage")
+
+        # EventIdentification
+        ei = ET.SubElement(root, "EventIdentification",
+                           EventActionCode=self.event_action,
+                           EventDateTime=self.event_datetime,
+                           EventOutcomeIndicator=self.event_outcome)
+
+        event_text = self._EVENT_ID_TEXT.get(self.event_id, self.event_id)
+        ET.SubElement(ei, "EventID",
+                      attrib={
+                          "csd-code": self.event_id,
+                          "codeSystemName": "DCM",
+                          "originalText": event_text,
+                      })
+
+        if self.event_type_code is not None:
+            ET.SubElement(ei, "EventTypeCode",
+                          attrib={
+                              "csd-code": self.event_type_code,
+                              "codeSystemName": self.event_type_code_scheme,
+                              "originalText": "AI Decision Sealed",
+                          })
+
+        # ActiveParticipant
+        ap_attribs = {
+            "UserID": self.user_id,
+            "UserIsRequestor": "true",
+        }
+        if self.user_name is not None:
+            ap_attribs["UserName"] = self.user_name
+        if self.network_access_point is not None:
+            ap_attribs["NetworkAccessPointID"] = self.network_access_point
+        ap = ET.SubElement(root, "ActiveParticipant", attrib=ap_attribs)
+        ET.SubElement(ap, "RoleIDCode",
+                      attrib={
+                          "csd-code": ROLE_APPLICATION,
+                          "codeSystemName": "DCM",
+                          "originalText": "Application",
+                      })
+
+        # AuditSourceIdentification
+        asi = ET.SubElement(root, "AuditSourceIdentification",
+                            AuditSourceID=self.audit_source_id)
+        ET.SubElement(asi, "AuditSourceTypeCode",
+                      attrib={
+                          "csd-code": "4",
+                          "codeSystemName": "DCM",
+                          "originalText": "Application Server",
+                      })
+
+        # ParticipantObjectIdentification
+        poi = ET.SubElement(root, "ParticipantObjectIdentification",
+                            ParticipantObjectID=self.participant_object_id,
+                            ParticipantObjectTypeCode=OBJ_TYPE_SYSTEM,
+                            ParticipantObjectTypeCodeRole=OBJ_ROLE_JOB)
+        ET.SubElement(poi, "ParticipantObjectIDTypeCode",
+                      attrib={
+                          "csd-code": "110182",
+                          "codeSystemName": "DCM",
+                          "originalText": "Node ID",
+                      })
+
+        for key, value in (self.participant_object_details or {}).items():
+            encoded = base64.b64encode(str(value).encode("utf-8")).decode("ascii")
+            ET.SubElement(poi, "ParticipantObjectDetail",
+                          type=key, value=encoded)
+
+        xml_body = ET.tostring(root, encoding="unicode", xml_declaration=False)
+        return '<?xml version="1.0" encoding="UTF-8"?>\n' + xml_body
+
+
+# ---------------------------------------------------------------------------
+# ATNAConnector
+# ---------------------------------------------------------------------------
+
+class ATNAConnector:
+    """Send ATNA-conformant audit messages and optionally seal them.
+
+    Wraps a Thessor Client and provides three independent capabilities:
+    - Building an ATNAAuditMessage from a SealResult.
+    - Shipping the message to a live ARR over UDP or TLS syslog.
+    - Sealing the message XML itself, making the audit trail tamper-evident.
+    """
+
+    def __init__(self, client: "Client"):  # noqa: F821 — forward ref, avoids import cycle
+        self.client = client
+
+    def build_audit_message(
+        self,
+        result: SealResult,
+        *,
+        user_id: str = "thessor-system",
+        event_id: str = EVENT_IMPORT,
+        event_action: str = ACTION_EXECUTE,
+        outcome: str = OUTCOME_SUCCESS,
+        extra_details: dict | None = None,
+    ) -> ATNAAuditMessage:
+        """Build an ATNAAuditMessage from a Thessor SealResult."""
+        details: dict = {
+            "ThessorEnvelopeID": result.envelope_id or "",
+            "ThessorVerifyURL": result.verify_url or "",
+            "SealVersion": result.seal_version or "",
+        }
+        if extra_details:
+            details.update(extra_details)
+
+        event_datetime = result.created_at or (datetime.utcnow().isoformat() + "Z")
+
+        return ATNAAuditMessage(
+            event_id=event_id,
+            event_action=event_action,
+            event_datetime=event_datetime,
+            event_outcome=outcome,
+            user_id=user_id,
+            audit_source_id=THESSOR_AUDIT_SOURCE_ID,
+            participant_object_id=result.envelope_id or "pending",
+            participant_object_details=details,
+            event_type_code=EVENT_AI_DECISION_SEALED,
+            event_type_code_scheme=THESSOR_CODING_SCHEME,
+        )
+
+    def send_udp(
+        self,
+        message: ATNAAuditMessage,
+        host: str,
+        port: int = DEFAULT_SYSLOG_PORT_UDP,
+    ) -> None:
+        """Send the audit message to an ARR via UDP syslog (RFC 5424).
+
+        Raises ConnectionError on any socket failure.
+        """
+        xml = message.to_xml()
+        timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+        hostname = socket.gethostname()
+        syslog_msg = f"<{_SYSLOG_PRIORITY}>1 {timestamp} {hostname} thessor - - - {xml}"
+        payload = syslog_msg.encode("utf-8")
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+                sock.sendto(payload, (host, port))
+        except socket.error as exc:
+            raise ConnectionError(f"UDP syslog send failed: {exc}") from exc
+
+    def send_tls(
+        self,
+        message: ATNAAuditMessage,
+        host: str,
+        port: int = DEFAULT_SYSLOG_PORT_TLS,
+        *,
+        ca_cert_path: str | None = None,
+        client_cert_path: str | None = None,
+        client_key_path: str | None = None,
+        timeout: float = 5.0,
+    ) -> None:
+        """Send the audit message to an ARR via TLS syslog (RFC 5425).
+
+        Uses octet-count framing: the message is prefixed with its byte length
+        followed by a space. Raises ConnectionError on any failure.
+        """
+        xml = message.to_xml()
+        timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+        hostname = socket.gethostname()
+        syslog_msg = f"<{_SYSLOG_PRIORITY}>1 {timestamp} {hostname} thessor - - - {xml}"
+        msg_bytes = syslog_msg.encode("utf-8")
+        framed = f"{len(msg_bytes)} ".encode("utf-8") + msg_bytes
+
+        try:
+            if ca_cert_path is not None:
+                ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+                ctx.load_verify_locations(ca_cert_path)
+            else:
+                ctx = ssl.create_default_context()
+
+            if client_cert_path and client_key_path:
+                ctx.load_cert_chain(client_cert_path, client_key_path)
+
+            with socket.create_connection((host, port), timeout=timeout) as raw_sock:
+                with ctx.wrap_socket(raw_sock, server_hostname=host) as tls_sock:
+                    tls_sock.sendall(framed)
+        except (socket.error, ssl.SSLError, OSError) as exc:
+            raise ConnectionError(f"TLS syslog send failed: {exc}") from exc
+
+    def seal_audit_message(
+        self,
+        message: ATNAAuditMessage,
+        *,
+        sync: bool = True,
+    ) -> SealResult:
+        """Seal the ATNA audit message XML itself via Thessor.
+
+        This makes the hospital's own audit trail tamper-evident: altering the
+        audit log after the fact breaks the Ed25519 signature.
+        """
+        xml = message.to_xml()
+        payload = {
+            "atna_xml": xml,
+            "envelope_id": message.participant_object_id,
+        }
+        return self.client.seal(
+            decision_id=f"atna-{message.participant_object_id}",
+            model_id="atna-audit",
+            model_version="1.0",
+            timestamp=message.event_datetime,
+            input_hash=sha256_hex(xml.encode("utf-8")),
+            output={
+                "event_id": message.event_id,
+                "outcome": message.event_outcome,
+            },
+            confidence_score=1.0,
+            policy_version="v1",
+            payload=payload,
+            sync=sync,
+        )
+
+    def build_and_seal(
+        self,
+        result: SealResult,
+        *,
+        send_to: str | None = None,
+        port: int = DEFAULT_SYSLOG_PORT_UDP,
+        use_tls: bool = False,
+        **build_kwargs,
+    ) -> tuple[ATNAAuditMessage, SealResult]:
+        """Build an ATNA message, optionally ship it, then seal it.
+
+        Steps:
+        1. build_audit_message(result, **build_kwargs)
+        2. If send_to is set: send via TLS or UDP accordingly.
+        3. seal_audit_message(message)
+        4. Return (ATNAAuditMessage, atna SealResult).
+        """
+        message = self.build_audit_message(result, **build_kwargs)
+
+        if send_to is not None:
+            if use_tls:
+                self.send_tls(message, send_to, port)
+            else:
+                self.send_udp(message, send_to, port)
+
+        atna_seal = self.seal_audit_message(message)
+        return message, atna_seal