constellation-node-sdk 1.0.1__py3-none-any.whl

constellation_node_sdk/runtime/app.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from typing import Any, Literal
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+from starlette.responses import Response
+
+from constellation_node_sdk.gate.registration import register_from_env
+from constellation_node_sdk.transport.packet import TransportPacket
+
+from .config import NodeRuntimeConfig, get_runtime_config
+from .errors import raise_http_exception
+from .execution import create_error_transport_packet, execute_transport_packet
+from .inbound_policy import validate_execute_ingress_packet, validate_relay_ingress_packet
+from .lifecycle import LifecycleHook, NoOpLifecycle
+from .observability import configure_logging, metrics_response, record_request, set_readiness
+from .preflight import run_preflight
+
+
+def _key_material_from_config(config: NodeRuntimeConfig) -> tuple[bytes | str | None, str | None]:
+    if config.signing_algorithm == "hmac-sha256":
+        return config.signing_key, config.signing_algorithm
+    if config.signing_algorithm == "ed25519":
+        return config.signing_private_key, config.signing_algorithm
+    return None, None
+
+
+def _resolve_route_validation(
+    *,
+    route_mode: Literal["execute", "relay"],
+    resolved_config: NodeRuntimeConfig,
+) -> dict[str, Any]:
+    if route_mode == "relay":
+        return {
+            "require_signature": resolved_config.relay_require_signature
+            if resolved_config.relay_require_signature is not None
+            else resolved_config.require_signature,
+            "verify_hop_signatures": resolved_config.relay_verify_hop_signatures
+            if resolved_config.relay_verify_hop_signatures is not None
+            else resolved_config.verify_hop_signatures,
+            "allowed_actions": (
+                resolved_config.relay_allowed_actions or resolved_config.allowed_actions or None
+            ),
+            "allowed_packet_types": (
+                resolved_config.relay_allowed_packet_types
+                or resolved_config.allowed_packet_types
+                or None
+            ),
+        }
+    return {
+        "require_signature": resolved_config.execute_require_signature
+        if resolved_config.execute_require_signature is not None
+        else resolved_config.require_signature,
+        "verify_hop_signatures": resolved_config.execute_verify_hop_signatures
+        if resolved_config.execute_verify_hop_signatures is not None
+        else resolved_config.verify_hop_signatures,
+        "allowed_actions": (
+            resolved_config.execute_allowed_actions or resolved_config.allowed_actions or None
+        ),
+        "allowed_packet_types": (
+            resolved_config.execute_allowed_packet_types
+            or resolved_config.allowed_packet_types
+            or None
+        ),
+    }
+
+
+async def _handle_transport_request(
+    request: Request,
+    *,
+    execution_mode: Literal["execute", "relay"],
+    resolved_config: NodeRuntimeConfig,
+    validate_ingress: Callable[[TransportPacket], None],
+) -> JSONResponse:
+    packet: TransportPacket | None = None
+    try:
+        body = await request.json()
+    except Exception as exc:
+        record_request(config=resolved_config, action="unknown", status="invalid_json")
+        raise HTTPException(status_code=400, detail=f"invalid JSON body: {exc}") from exc
+
+    try:
+        if not isinstance(body, dict):
+            raise ValueError("request body must be a JSON object")
+        packet = TransportPacket.model_validate(body)
+        if resolved_config.enforce_gate_only_ingress:
+            validate_ingress(packet)
+
+        route_validation = _resolve_route_validation(
+            route_mode=execution_mode,
+            resolved_config=resolved_config,
+        )
+
+        response_signing_key, response_signing_algorithm = _key_material_from_config(
+            resolved_config
+        )
+
+        response_packet = await execute_transport_packet(
+            packet,
+            node_name=resolved_config.node_name,
+            signing_key=(
+                response_signing_key if response_signing_algorithm == "hmac-sha256" else None
+            ),
+            signing_private_key=(
+                str(response_signing_key)
+                if response_signing_algorithm == "ed25519" and response_signing_key
+                else None
+            ),
+            signing_key_id=resolved_config.signing_key_id,
+            signing_algorithm=response_signing_algorithm,
+            verifying_keys=resolved_config.verifying_keys,
+            require_signature=route_validation["require_signature"],
+            allowed_actions=route_validation["allowed_actions"],
+            allowed_packet_types=route_validation["allowed_packet_types"],
+            required_idempotency_actions=(resolved_config.require_idempotency_for_actions or None),
+            replay_enabled=resolved_config.replay_enabled,
+            dev_mode=resolved_config.dev_mode,
+            verify_hop_signatures=route_validation["verify_hop_signatures"],
+            allowed_clock_skew_seconds=resolved_config.allowed_clock_skew_seconds,
+            max_packet_bytes=resolved_config.max_packet_bytes,
+            max_hop_depth=resolved_config.max_hop_depth,
+            max_delegation_depth=resolved_config.max_delegation_depth,
+            max_attachments=resolved_config.max_attachments,
+            max_attachment_size_bytes=resolved_config.max_attachment_size_bytes,
+            allowed_attachment_schemes=resolved_config.attachment_allowed_schemes,
+            allow_private_attachment_hosts=resolved_config.allow_private_attachment_hosts,
+        )
+
+        status = str(response_packet.payload.get("status", "completed")).strip().lower()
+        record_request(config=resolved_config, action=packet.header.action, status=status)
+        return JSONResponse(content=response_packet.model_dump_json_dict())
+
+    except Exception as exc:
+        if packet is not None and resolved_config.return_transport_errors:
+            response_signing_key, response_signing_algorithm = _key_material_from_config(
+                resolved_config
+            )
+            failure_packet = create_error_transport_packet(
+                packet,
+                exc,
+                node_name=resolved_config.node_name,
+                signing_key=(
+                    response_signing_key if response_signing_algorithm == "hmac-sha256" else None
+                ),
+                signing_private_key=(
+                    str(response_signing_key)
+                    if response_signing_algorithm == "ed25519" and response_signing_key
+                    else None
+                ),
+                signing_key_id=resolved_config.signing_key_id,
+                signing_algorithm=response_signing_algorithm,
+                expose_internal_errors=resolved_config.expose_internal_errors,
+            )
+            record_request(
+                config=resolved_config,
+                action=packet.header.action,
+                status="failed",
+            )
+            return JSONResponse(content=failure_packet.model_dump_json_dict())
+
+        record_request(
+            config=resolved_config,
+            action="unknown" if packet is None else packet.header.action,
+            status="error",
+        )
+        raise_http_exception(exc)
+
+
+def create_node_app(
+    *,
+    service_name: str | None = None,
+    version: str | None = None,
+    lifecycle_hook: LifecycleHook | None = None,
+    config: NodeRuntimeConfig | None = None,
+    auto_register_with_gate: bool = True,
+) -> FastAPI:
+    resolved_config = config or get_runtime_config()
+    resolved_service_name = service_name or resolved_config.service_name
+    resolved_version = version or resolved_config.service_version
+    resolved_lifecycle = lifecycle_hook or NoOpLifecycle()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        configure_logging(resolved_config)
+        run_preflight(resolved_config)
+
+        app.state.runtime_ready = False
+        set_readiness(config=resolved_config, ready=False)
+
+        await resolved_lifecycle.startup()
+
+        if auto_register_with_gate and resolved_config.gate_url:
+            await register_from_env()
+
+        app.state.runtime_ready = True
+        set_readiness(config=resolved_config, ready=True)
+
+        yield
+
+        app.state.runtime_ready = False
+        set_readiness(config=resolved_config, ready=False)
+        await resolved_lifecycle.shutdown()
+
+    app = FastAPI(
+        title=resolved_service_name,
+        version=resolved_version,
+        lifespan=lifespan,
+    )
+    app.state.runtime_ready = False
+
+    @app.get("/v1/health")
+    async def health() -> dict[str, Any]:
+        return {
+            "status": "healthy" if bool(getattr(app.state, "runtime_ready", False)) else "starting",
+            "service_name": resolved_config.service_name,
+            "service_version": resolved_config.service_version,
+            "node_name": resolved_config.node_name,
+            "ready": bool(getattr(app.state, "runtime_ready", False)),
+        }
+
+    @app.get("/metrics")
+    async def metrics() -> Response:
+        return metrics_response()
+
+    @app.post("/v1/execute")
+    async def execute(request: Request) -> JSONResponse:
+        def _validate_execute_ingress(packet: TransportPacket) -> None:
+            validate_execute_ingress_packet(
+                packet,
+                local_node=resolved_config.node_name,
+                gate_node_name=resolved_config.gate_node_name,
+                require_route_kind=resolved_config.require_gate_mediation_provenance,
+            )
+
+        return await _handle_transport_request(
+            request,
+            execution_mode="execute",
+            resolved_config=resolved_config,
+            validate_ingress=_validate_execute_ingress,
+        )
+
+    if resolved_config.enable_relay_route:
+
+        @app.post("/v1/relay")
+        async def relay(request: Request) -> JSONResponse:
+            def _validate_relay_ingress(packet: TransportPacket) -> None:
+                validate_relay_ingress_packet(
+                    packet,
+                    local_node=resolved_config.node_name,
+                    gate_node_name=resolved_config.gate_node_name,
+                    require_route_kind=resolved_config.require_gate_mediation_provenance,
+                    allowed_actions=(
+                        resolved_config.relay_allowed_actions
+                        or resolved_config.allowed_actions
+                        or None
+                    ),
+                    allowed_packet_types=(
+                        resolved_config.relay_allowed_packet_types
+                        or resolved_config.allowed_packet_types
+                        or None
+                    ),
+                )
+
+            return await _handle_transport_request(
+                request,
+                execution_mode="relay",
+                resolved_config=resolved_config,
+                validate_ingress=_validate_relay_ingress,
+            )
+
+    return app

constellation_node_sdk/runtime/config.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+_ALLOWED_ENVIRONMENTS = {"local", "dev", "test", "staging", "prod"}
+_ALLOWED_SIGNING_ALGORITHMS = {"hmac-sha256", "ed25519"}
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_tuple(name: str) -> tuple[str, ...]:
+    raw = os.getenv(name, "")
+    return tuple(item.strip() for item in raw.split(",") if item.strip())
+
+
+def _env_json_map(name: str) -> dict[str, str]:
+    raw = os.getenv(name, "").strip()
+    if not raw:
+        return {}
+    parsed = json.loads(raw)
+    if not isinstance(parsed, dict):
+        raise ValueError(f"{name} must be a JSON object")
+    result: dict[str, str] = {}
+    for key, value in parsed.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise ValueError(f"{name} must map strings to strings")
+        result[key] = value
+    return result
+
+
+class NodeRuntimeConfig(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    environment: str
+    node_name: str
+    service_name: str
+    service_version: str
+
+    dev_mode: bool = False
+    require_signature: bool = False
+    expose_internal_errors: bool = False
+    return_transport_errors: bool = True
+
+    signing_algorithm: str = "hmac-sha256"
+    signing_key: str | None = None
+    signing_private_key: str | None = None
+    signing_key_id: str | None = None
+    verifying_keys: dict[str, str] = Field(default_factory=dict)
+
+    allowed_actions: tuple[str, ...] = ()
+    allowed_packet_types: tuple[str, ...] = ("request", "command", "delegation", "replay_request")
+    require_idempotency_for_actions: tuple[str, ...] = ()
+
+    allowed_clock_skew_seconds: int = Field(default=30, ge=0)
+    max_packet_bytes: int = Field(default=262_144, ge=1024)
+    max_hop_depth: int = Field(default=64, ge=1)
+    max_delegation_depth: int = Field(default=8, ge=1)
+    max_attachments: int = Field(default=32, ge=0)
+    max_attachment_size_bytes: int = Field(default=10_485_760, ge=0)
+    attachment_allowed_schemes: tuple[str, ...] = ()
+    allow_private_attachment_hosts: bool = False
+
+    replay_enabled: bool = True
+    verify_hop_signatures: bool = False
+
+    gate_node_name: str = "gate"
+    enforce_gate_only_ingress: bool = True
+    enable_relay_route: bool = True
+    require_gate_mediation_provenance: bool = True
+
+    execute_require_signature: bool | None = None
+    execute_verify_hop_signatures: bool | None = None
+    execute_allowed_actions: tuple[str, ...] = ()
+    execute_allowed_packet_types: tuple[str, ...] = ()
+
+    relay_require_signature: bool | None = None
+    relay_verify_hop_signatures: bool | None = None
+    relay_allowed_actions: tuple[str, ...] = ()
+    relay_allowed_packet_types: tuple[str, ...] = (
+        "request",
+        "command",
+        "delegation",
+        "replay_request",
+    )
+
+    gate_url: str | None = None
+    # Default to loopback — containers must set HOST=0.0.0.0 explicitly via env var.
+    # This prevents accidental public binding on bare-metal or dev environments.
+    host: str = "127.0.0.1"
+    port: int = Field(default=8000, ge=1, le=65535)
+
+    @field_validator(
+        "environment",
+        "node_name",
+        "gate_node_name",
+        "service_name",
+        "service_version",
+        "signing_algorithm",
+        "host",
+    )
+    @classmethod
+    def validate_required_strings(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("field must not be empty")
+        return normalized
+
+    @field_validator("environment")
+    @classmethod
+    def validate_environment(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in _ALLOWED_ENVIRONMENTS:
+            raise ValueError(f"environment must be one of {sorted(_ALLOWED_ENVIRONMENTS)}")
+        return normalized
+
+    @field_validator("signing_algorithm")
+    @classmethod
+    def validate_signing_algorithm(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized not in _ALLOWED_SIGNING_ALGORITHMS:
+            raise ValueError(
+                f"signing_algorithm must be one of {sorted(_ALLOWED_SIGNING_ALGORITHMS)}"
+            )
+        return normalized
+
+    @field_validator(
+        "allowed_actions",
+        "allowed_packet_types",
+        "require_idempotency_for_actions",
+        "attachment_allowed_schemes",
+        "execute_allowed_actions",
+        "execute_allowed_packet_types",
+        "relay_allowed_actions",
+        "relay_allowed_packet_types",
+    )
+    @classmethod
+    def validate_string_tuples(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        normalized = tuple(item.strip().lower() for item in value if item.strip())
+        if len(set(normalized)) != len(normalized):
+            raise ValueError("tuple entries must not contain duplicates")
+        return normalized
+
+    @field_validator("signing_key_id")
+    @classmethod
+    def validate_optional_key_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("signing_key_id must not be blank")
+        return normalized
+
+    @field_validator("verifying_keys")
+    @classmethod
+    def validate_verifying_keys(cls, value: dict[str, str]) -> dict[str, str]:
+        normalized: dict[str, str] = {}
+        for key_id, key_value in value.items():
+            normalized_key = key_id.strip()
+            normalized_value = key_value.strip()
+            if not normalized_key or not normalized_value:
+                raise ValueError("verifying_keys must not contain blank keys or values")
+            normalized[normalized_key] = normalized_value
+        return normalized
+
+    @field_validator("gate_url")
+    @classmethod
+    def validate_gate_url(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip().rstrip("/")
+        if not normalized:
+            raise ValueError("gate_url must not be blank")
+        if not (normalized.startswith("http://") or normalized.startswith("https://")):
+            raise ValueError("gate_url must start with http:// or https://")
+        return normalized
+
+    @model_validator(mode="after")
+    def validate_security_profile(self) -> NodeRuntimeConfig:
+        if self.environment in {"staging", "prod"} and self.dev_mode:
+            raise ValueError("dev_mode cannot be enabled in staging or prod")
+
+        if self.require_signature:
+            if self.signing_algorithm == "hmac-sha256" and not self.signing_key:
+                raise ValueError("hmac-sha256 requires signing_key when require_signature=true")
+            if self.signing_algorithm == "ed25519" and not self.signing_private_key:
+                raise ValueError("ed25519 requires signing_private_key when require_signature=true")
+
+        if self.signing_algorithm == "ed25519" and self.signing_key is not None:
+            raise ValueError("signing_key must not be used with ed25519")
+
+        known_actions = set(self.allowed_actions) | set(self.execute_allowed_actions)
+        invalid_idempotency = set(self.require_idempotency_for_actions) - known_actions
+        if invalid_idempotency:
+            invalid = ", ".join(sorted(invalid_idempotency))
+            raise ValueError(f"require_idempotency_for_actions contains unknown actions: {invalid}")
+
+        if self.max_attachment_size_bytes > self.max_packet_bytes:
+            raise ValueError("max_attachment_size_bytes must not exceed max_packet_bytes")
+
+        if self.max_attachments > 0 and not self.attachment_allowed_schemes:
+            raise ValueError(
+                "attachment_allowed_schemes must be configured when attachments are enabled"
+            )
+
+        execute_actions = (
+            set(self.execute_allowed_actions)
+            if self.execute_allowed_actions
+            else set(self.allowed_actions)
+        )
+        invalid_execute_idempotency = set(self.require_idempotency_for_actions) - execute_actions
+        if invalid_execute_idempotency:
+            invalid = ", ".join(sorted(invalid_execute_idempotency))
+            raise ValueError(
+                f"require_idempotency_for_actions contains unknown execute actions: {invalid}"
+            )
+
+        return self
+
+    def resolve_verifying_key(self, key_id: str | None) -> str | bytes | None:
+        if key_id is None:
+            return None
+        if key_id in self.verifying_keys:
+            return self.verifying_keys[key_id]
+        if self.signing_key_id is not None and key_id == self.signing_key_id:
+            if self.signing_algorithm == "hmac-sha256":
+                return self.signing_key
+        return None
+
+
+@lru_cache
+def get_runtime_config() -> NodeRuntimeConfig:
+    environment = os.getenv("L9_ENVIRONMENT", "local").strip().lower() or "local"
+    dev_mode = _env_bool("L9_DEV_MODE", False)
+    return NodeRuntimeConfig(
+        environment=environment,
+        node_name=os.getenv("L9_NODE_NAME", "unknown-node"),
+        service_name=os.getenv("L9_SERVICE_NAME", os.getenv("L9_NODE_NAME", "unknown-node")),
+        service_version=os.getenv("L9_SERVICE_VERSION", "1.0.0"),
+        dev_mode=dev_mode,
+        require_signature=_env_bool("L9_REQUIRE_SIGNATURE", False),
+        expose_internal_errors=_env_bool("L9_EXPOSE_INTERNAL_ERRORS", False),
+        return_transport_errors=_env_bool("L9_RETURN_TRANSPORT_ERRORS", True),
+        signing_algorithm=os.getenv("L9_SIGNING_ALGORITHM", "hmac-sha256"),
+        signing_key=os.getenv("L9_SIGNING_KEY") or os.getenv("L9_SIGNING_SECRET"),
+        signing_private_key=os.getenv("L9_SIGNING_PRIVATE_KEY"),
+        signing_key_id=os.getenv("L9_SIGNING_KEY_ID"),
+        verifying_keys=_env_json_map("L9_VERIFYING_KEYS_JSON"),
+        allowed_actions=_env_tuple("L9_ALLOWED_ACTIONS"),
+        allowed_packet_types=_env_tuple("L9_ALLOWED_PACKET_TYPES")
+        or ("request", "command", "delegation", "replay_request"),
+        require_idempotency_for_actions=_env_tuple("L9_REQUIRE_IDEMPOTENCY_FOR_ACTIONS"),
+        allowed_clock_skew_seconds=int(os.getenv("L9_ALLOWED_CLOCK_SKEW_SECONDS", "30")),
+        max_packet_bytes=int(os.getenv("L9_MAX_PACKET_BYTES", "262144")),
+        max_hop_depth=int(os.getenv("L9_MAX_HOP_DEPTH", "64")),
+        max_delegation_depth=int(os.getenv("L9_MAX_DELEGATION_DEPTH", "8")),
+        max_attachments=int(os.getenv("L9_MAX_ATTACHMENTS", "32")),
+        max_attachment_size_bytes=int(os.getenv("L9_MAX_ATTACHMENT_SIZE_BYTES", "10485760")),
+        attachment_allowed_schemes=_env_tuple("L9_ATTACHMENT_ALLOWED_SCHEMES"),
+        allow_private_attachment_hosts=_env_bool("L9_ALLOW_PRIVATE_ATTACHMENT_HOSTS", False),
+        replay_enabled=_env_bool("L9_REPLAY_ENABLED", True),
+        verify_hop_signatures=_env_bool("L9_VERIFY_HOP_SIGNATURES", False),
+        gate_node_name=os.getenv("L9_GATE_NODE_NAME", "gate"),
+        enforce_gate_only_ingress=_env_bool("L9_ENFORCE_GATE_ONLY_INGRESS", True),
+        enable_relay_route=_env_bool("L9_ENABLE_RELAY_ROUTE", True),
+        require_gate_mediation_provenance=_env_bool("L9_REQUIRE_GATE_MEDIATION_PROVENANCE", True),
+        execute_require_signature=(
+            _env_bool("L9_EXECUTE_REQUIRE_SIGNATURE", False)
+            if os.getenv("L9_EXECUTE_REQUIRE_SIGNATURE") is not None
+            else None
+        ),
+        execute_verify_hop_signatures=(
+            _env_bool("L9_EXECUTE_VERIFY_HOP_SIGNATURES", False)
+            if os.getenv("L9_EXECUTE_VERIFY_HOP_SIGNATURES") is not None
+            else None
+        ),
+        execute_allowed_actions=_env_tuple("L9_EXECUTE_ALLOWED_ACTIONS"),
+        execute_allowed_packet_types=_env_tuple("L9_EXECUTE_ALLOWED_PACKET_TYPES"),
+        relay_require_signature=(
+            _env_bool("L9_RELAY_REQUIRE_SIGNATURE", False)
+            if os.getenv("L9_RELAY_REQUIRE_SIGNATURE") is not None
+            else None
+        ),
+        relay_verify_hop_signatures=(
+            _env_bool("L9_RELAY_VERIFY_HOP_SIGNATURES", False)
+            if os.getenv("L9_RELAY_VERIFY_HOP_SIGNATURES") is not None
+            else None
+        ),
+        relay_allowed_actions=_env_tuple("L9_RELAY_ALLOWED_ACTIONS"),
+        relay_allowed_packet_types=(
+            _env_tuple("L9_RELAY_ALLOWED_PACKET_TYPES")
+            or ("request", "command", "delegation", "replay_request")
+        ),
+        gate_url=os.getenv("GATE_URL"),
+        # HOST env var overrides the safe 127.0.0.1 default.
+        # In containers set HOST=0.0.0.0. On bare metal leave unset.
+        host=os.getenv("HOST", "127.0.0.1"),
+        port=int(os.getenv("PORT", "8000")),
+    )

constellation_node_sdk/runtime/errors.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import NoReturn
+
+from fastapi import HTTPException
+
+from constellation_node_sdk.transport.errors import (
+    PacketSizeError,
+    SchemaVersionError,
+    TenantMutationError,
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportExpiredError,
+    TransportIntegrityError,
+    TransportNotYetValidError,
+    TransportValidationError,
+)
+
+
+class RuntimeErrorBase(Exception):
+    """Base exception for runtime-layer failures."""
+
+
+class RuntimeConfigurationError(RuntimeErrorBase):
+    """Raised when runtime configuration is invalid or incomplete."""
+
+
+class RuntimeValidationError(RuntimeErrorBase):
+    """Raised when an inbound request fails runtime validation."""
+
+
+class RuntimeExecutionError(RuntimeErrorBase):
+    """Raised when handler execution fails within the runtime shell."""
+
+
+@dataclass(frozen=True)
+class RuntimeErrorDetail:
+    code: str
+    message: str
+    status_code: int
+
+
+def classify_exception(exc: Exception) -> RuntimeErrorDetail:
+    """
+    Map runtime and transport exceptions to safe HTTP-facing error details.
+    """
+    if isinstance(
+        exc,
+        (
+            ValueError,
+            TransportValidationError,
+            TransportIntegrityError,
+            PacketSizeError,
+            SchemaVersionError,
+            TenantMutationError,
+        ),
+    ):
+        return RuntimeErrorDetail(
+            code="invalid_request",
+            message=str(exc),
+            status_code=400,
+        )
+
+    if isinstance(exc, (TransportAuthenticationError,)):
+        return RuntimeErrorDetail(
+            code="authentication_failed",
+            message="transport authentication failed",
+            status_code=401,
+        )
+
+    if isinstance(exc, (TransportAuthorizationError,)):
+        return RuntimeErrorDetail(
+            code="authorization_failed",
+            message="transport authorization failed",
+            status_code=403,
+        )
+
+    if isinstance(exc, (TransportExpiredError, TransportNotYetValidError)):
+        return RuntimeErrorDetail(
+            code="temporal_validity_failed",
+            message=str(exc),
+            status_code=409,
+        )
+
+    if isinstance(exc, TimeoutError):
+        return RuntimeErrorDetail(
+            code="execution_timeout",
+            message="handler execution timed out",
+            status_code=504,
+        )
+
+    return RuntimeErrorDetail(
+        code="internal_error",
+        message="internal server error",
+        status_code=500,
+    )
+
+
+def raise_http_exception(exc: Exception) -> NoReturn:
+    """
+    Raise a FastAPI HTTPException from a classified runtime exception.
+    Always raises — annotated NoReturn so mypy understands no return sentinel needed.
+    """
+    detail = classify_exception(exc)
+    raise HTTPException(
+        status_code=detail.status_code,
+        detail={
+            "code": detail.code,
+            "message": detail.message,
+        },
+    ) from exc