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

constellation_node_sdk/runtime/execution.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Callable
+
+from constellation_node_sdk.security.signing import sign_transport_packet
+from constellation_node_sdk.security.validation import validate_transport_packet
+from constellation_node_sdk.transport.hop_trace import make_execution_hop, make_response_hop
+from constellation_node_sdk.transport.packet import TransportPacket
+
+from .handlers import get_handler
+
+
+def _resolve_signing_material(
+    *,
+    signing_key: bytes | str | None,
+    signing_private_key: str | None,
+    signing_algorithm: str | None,
+) -> bytes | str | None:
+    if signing_algorithm is None:
+        return signing_key if signing_key is not None else signing_private_key
+    normalized = signing_algorithm.strip().lower()
+    if normalized == "hmac-sha256":
+        return signing_key
+    if normalized == "ed25519":
+        return signing_private_key
+    raise ValueError(f"unsupported signing algorithm: {normalized}")
+
+
+def _build_key_resolver(
+    *,
+    signing_key: bytes | str | None,
+    verifying_keys: dict[str, str] | None,
+) -> Callable[[str | None], str | bytes | None] | dict[str, str] | None:
+    if verifying_keys:
+        return verifying_keys
+    if signing_key is None:
+        return None
+    return lambda _key_id: signing_key
+
+
+async def _invoke_handler(handler: Callable[..., object], packet: TransportPacket) -> object:
+    parameters = list(inspect.signature(handler).parameters.values())
+
+    if len(parameters) == 1:
+        candidate = handler(packet)
+    elif len(parameters) == 2:
+        candidate = handler(packet.tenant.org_id, packet.payload)
+    elif len(parameters) == 0:
+        candidate = handler()
+    else:
+        candidate = handler(packet.tenant.org_id, packet.payload, packet)
+
+    if inspect.isawaitable(candidate):
+        return await candidate
+    return candidate
+
+
+def _extract_payload(result: object) -> dict[str, object]:
+    if isinstance(result, dict):
+        return result
+    raise TypeError(f"handler must return dict or TransportPacket, got {type(result)!r}")
+
+
+async def execute_transport_packet(
+    packet: TransportPacket,
+    *,
+    node_name: str,
+    signing_key: bytes | str | None = None,
+    signing_private_key: str | None = None,
+    signing_key_id: str | None = None,
+    signing_algorithm: str | None = None,
+    verifying_keys: dict[str, str] | None = None,
+    require_signature: bool = False,
+    allowed_actions: tuple[str, ...] | None = None,
+    allowed_packet_types: tuple[str, ...] | None = None,
+    required_idempotency_actions: tuple[str, ...] | None = None,
+    replay_enabled: bool = True,
+    dev_mode: bool = False,
+    verify_hop_signatures: bool = False,
+    allowed_clock_skew_seconds: int = 30,
+    max_packet_bytes: int = 262_144,
+    max_hop_depth: int = 64,
+    max_delegation_depth: int = 8,
+    max_attachments: int = 32,
+    max_attachment_size_bytes: int = 10_485_760,
+    allowed_attachment_schemes: tuple[str, ...] = (),
+    allow_private_attachment_hosts: bool = False,
+) -> TransportPacket:
+    normalized_node_name = node_name.strip().lower()
+    key_resolver = _build_key_resolver(
+        signing_key=signing_key,
+        verifying_keys=verifying_keys,
+    )
+
+    validate_transport_packet(
+        packet,
+        key_resolver=key_resolver,
+        require_signature=require_signature,
+        max_packet_bytes=max_packet_bytes,
+        max_hop_depth=max_hop_depth,
+        max_delegation_depth=max_delegation_depth,
+        max_attachments=max_attachments,
+        max_attachment_size_bytes=max_attachment_size_bytes,
+        allowed_attachment_schemes=allowed_attachment_schemes,
+        allow_private_attachment_hosts=allow_private_attachment_hosts,
+        allowed_clock_skew_seconds=allowed_clock_skew_seconds,
+        local_node=normalized_node_name,
+        allowed_actions=allowed_actions,
+        allowed_packet_types=allowed_packet_types,
+        required_idempotency_actions=required_idempotency_actions,
+        replay_enabled=replay_enabled,
+        dev_mode=dev_mode,
+        verify_hop_signatures=verify_hop_signatures,
+        hop_key_resolver=key_resolver,
+    )
+
+    handler = get_handler(packet.header.action)
+    if handler is None:
+        raise ValueError(f"no handler registered for action: {packet.header.action}")
+
+    processing_packet = packet.with_hop(
+        make_execution_hop(
+            packet=packet,
+            node=normalized_node_name,
+            action=packet.header.action,
+            status="processing",
+        )
+    )
+
+    try:
+        result = await asyncio.wait_for(
+            _invoke_handler(handler, processing_packet),
+            timeout=processing_packet.header.timeout_ms / 1000,
+        )
+    except TimeoutError as exc:
+        raise TimeoutError(
+            f"handler timeout after {processing_packet.header.timeout_ms}ms"
+        ) from exc
+
+    if isinstance(result, TransportPacket):
+        response_packet = result
+    else:
+        payload = _extract_payload(result)
+        response_packet = processing_packet.derive(
+            packet_type="response",
+            source_node=normalized_node_name,
+            destination_node=processing_packet.address.reply_to,
+            reply_to=normalized_node_name,
+            payload=payload,
+        )
+
+    payload_status = str(response_packet.payload.get("status", "completed")).strip().lower()
+    if payload_status not in {
+        "received",
+        "validated",
+        "processing",
+        "delegated",
+        "completed",
+        "failed",
+    }:
+        payload_status = "completed"
+
+    response_packet = response_packet.with_hop(
+        make_response_hop(
+            packet=response_packet,
+            node=normalized_node_name,
+            action=response_packet.header.action,
+            status=payload_status,
+        )
+    )
+
+    resolved_signing_key = _resolve_signing_material(
+        signing_key=signing_key,
+        signing_private_key=signing_private_key,
+        signing_algorithm=signing_algorithm,
+    )
+    if resolved_signing_key is not None:
+        if signing_key_id is None or signing_algorithm is None:
+            raise ValueError(
+                "signing_key_id and signing_algorithm are required when signing responses"
+            )
+        response_packet = sign_transport_packet(
+            response_packet,
+            key=resolved_signing_key,
+            key_id=signing_key_id,
+            algorithm=signing_algorithm,
+        )
+
+    return response_packet
+
+
+def create_error_transport_packet(
+    packet: TransportPacket,
+    error: Exception,
+    *,
+    node_name: str,
+    signing_key: bytes | str | None = None,
+    signing_private_key: str | None = None,
+    signing_key_id: str | None = None,
+    signing_algorithm: str | None = None,
+    expose_internal_errors: bool = False,
+) -> TransportPacket:
+    normalized_node_name = node_name.strip().lower()
+    client_message = str(error) if expose_internal_errors else error.__class__.__name__
+
+    response_packet = packet.derive(
+        packet_type="failure",
+        source_node=normalized_node_name,
+        destination_node=packet.address.reply_to,
+        reply_to=normalized_node_name,
+        payload={
+            "status": "failed",
+            "error": error.__class__.__name__,
+            "message": client_message,
+            "packet_id": str(packet.header.packet_id),
+        },
+    )
+
+    response_packet = response_packet.with_hop(
+        make_response_hop(
+            packet=response_packet,
+            node=normalized_node_name,
+            action=response_packet.header.action,
+            status="failed",
+            error_code=error.__class__.__name__,
+            error_message=str(error) if expose_internal_errors else client_message,
+        )
+    )
+
+    resolved_signing_key = _resolve_signing_material(
+        signing_key=signing_key,
+        signing_private_key=signing_private_key,
+        signing_algorithm=signing_algorithm,
+    )
+    if resolved_signing_key is not None:
+        if signing_key_id is None or signing_algorithm is None:
+            raise ValueError(
+                "signing_key_id and signing_algorithm are required when signing error responses"
+            )
+        response_packet = sign_transport_packet(
+            response_packet,
+            key=resolved_signing_key,
+            key_id=signing_key_id,
+            algorithm=signing_algorithm,
+        )
+
+    return response_packet

constellation_node_sdk/runtime/handlers.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+_HANDLER_REGISTRY: dict[str, Callable[..., Any]] = {}
+
+
+def register_handler(action: str, fn: Callable[..., Any] | None = None) -> Callable[..., Any]:
+    """
+    Register a runtime handler for a transport action.
+    """
+    normalized_action = action.strip().lower()
+    if not normalized_action:
+        raise ValueError("action must not be empty")
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        _HANDLER_REGISTRY[normalized_action] = func
+        return func
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def get_handler(action: str) -> Callable[..., Any] | None:
+    """
+    Resolve a handler by exact action, falling back to '*' if present.
+    """
+    normalized_action = action.strip().lower()
+    return _HANDLER_REGISTRY.get(normalized_action) or _HANDLER_REGISTRY.get("*")
+
+
+def clear_handlers() -> None:
+    """
+    Clear all registered handlers.
+    """
+    _HANDLER_REGISTRY.clear()
+
+
+def registered_actions() -> tuple[str, ...]:
+    """
+    Return the registered action names in sorted order.
+    """
+    return tuple(sorted(_HANDLER_REGISTRY.keys()))

constellation_node_sdk/runtime/inbound_policy.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+def assert_gate_source(packet: TransportPacket, *, gate_node_name: str = "gate") -> None:
+    expected = gate_node_name.strip().lower()
+    actual = packet.address.source_node.strip().lower()
+    if actual != expected:
+        raise ValueError(f"inbound packets must originate from {expected!r}, got {actual!r}")
+
+
+def assert_packet_targets_local_node(packet: TransportPacket, *, local_node: str) -> None:
+    expected = local_node.strip().lower()
+    actual = packet.address.destination_node.strip().lower()
+    if actual != expected:
+        raise ValueError(
+            f"inbound packet destination_node {actual!r} does not match local node {expected!r}"
+        )
+
+
+def assert_gate_mediated_provenance(
+    packet: TransportPacket,
+    *,
+    allow_route_kinds: tuple[str, ...],
+    require_route_kind: bool = True,
+) -> None:
+    if not packet.provenance.resolved_by_gate:
+        raise ValueError("inbound packet provenance.resolved_by_gate must be true")
+
+    if packet.provenance.origin_kind not in {"client", "node", "gate"}:
+        raise ValueError("invalid inbound provenance.origin_kind")
+
+    route_kind = packet.provenance.route_kind
+    if route_kind is None:
+        if require_route_kind:
+            raise ValueError("inbound packet provenance.route_kind is required")
+        return
+
+    normalized_route_kind = route_kind.strip().lower()
+    normalized_allowed = tuple(value.strip().lower() for value in allow_route_kinds)
+    if normalized_route_kind not in normalized_allowed:
+        raise ValueError(
+            f"inbound packet provenance.route_kind must be one of "
+            f"{normalized_allowed}, got {normalized_route_kind!r}"
+        )
+
+
+def validate_execute_ingress_packet(
+    packet: TransportPacket,
+    *,
+    local_node: str,
+    gate_node_name: str = "gate",
+    require_route_kind: bool = True,
+) -> None:
+    assert_gate_source(packet, gate_node_name=gate_node_name)
+    assert_packet_targets_local_node(packet, local_node=local_node)
+    assert_gate_mediated_provenance(
+        packet,
+        allow_route_kinds=("external_ingress",),
+        require_route_kind=require_route_kind,
+    )
+
+
+def validate_relay_ingress_packet(
+    packet: TransportPacket,
+    *,
+    local_node: str,
+    gate_node_name: str = "gate",
+    require_route_kind: bool = True,
+    allowed_actions: tuple[str, ...] | None = None,
+    allowed_packet_types: tuple[str, ...] | None = None,
+) -> None:
+    assert_gate_source(packet, gate_node_name=gate_node_name)
+    assert_packet_targets_local_node(packet, local_node=local_node)
+    assert_gate_mediated_provenance(
+        packet,
+        allow_route_kinds=("gate_relay",),
+        require_route_kind=require_route_kind,
+    )
+
+    if allowed_actions and packet.header.action not in allowed_actions:
+        raise ValueError(f"relay action {packet.header.action!r} is not allowed")
+
+    if allowed_packet_types and packet.header.packet_type not in allowed_packet_types:
+        raise ValueError(f"relay packet_type {packet.header.packet_type!r} is not allowed")

constellation_node_sdk/runtime/lifecycle.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LifecycleHook(ABC):
+    """
+    Minimal lifecycle interface for node startup and shutdown hooks.
+    """
+
+    @abstractmethod
+    async def startup(self) -> None:
+        """Run node-specific startup logic."""
+
+    @abstractmethod
+    async def shutdown(self) -> None:
+        """Run node-specific shutdown logic."""
+
+
+class NoOpLifecycle(LifecycleHook):
+    """
+    Default lifecycle hook when a node has no custom startup or shutdown behavior.
+    """
+
+    async def startup(self) -> None:
+        return None
+
+    async def shutdown(self) -> None:
+        return None

constellation_node_sdk/runtime/observability.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import logging
+import sys
+
+from prometheus_client import (
+    CONTENT_TYPE_LATEST,
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    generate_latest,
+)
+from pythonjsonlogger import jsonlogger
+from starlette.responses import Response
+
+from .config import NodeRuntimeConfig
+
+REGISTRY = CollectorRegistry(auto_describe=True)
+REQUESTS_TOTAL = Counter(
+    "constellation_node_requests_total",
+    "Total execute requests",
+    ["service", "action", "status"],
+    registry=REGISTRY,
+)
+READY_GAUGE = Gauge(
+    "constellation_node_ready",
+    "Service readiness",
+    ["service"],
+    registry=REGISTRY,
+)
+
+
+def configure_logging(config: NodeRuntimeConfig) -> None:
+    """
+    Configure root logging for the node runtime.
+    """
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(
+        jsonlogger.JsonFormatter(  # type: ignore[attr-defined]
+            "%(asctime)s %(levelname)s %(name)s %(message)s"
+        )
+    )
+    root.addHandler(handler)
+
+
+def set_readiness(*, config: NodeRuntimeConfig, ready: bool) -> None:
+    """
+    Update readiness gauge for the current service.
+    """
+    READY_GAUGE.labels(service=config.service_name).set(1 if ready else 0)
+
+
+def record_request(*, config: NodeRuntimeConfig, action: str, status: str) -> None:
+    """
+    Increment request counter for an executed action.
+    """
+    REQUESTS_TOTAL.labels(
+        service=config.service_name,
+        action=action.strip().lower(),
+        status=status.strip().lower(),
+    ).inc()
+
+
+def metrics_response() -> Response:
+    """
+    Return the Prometheus metrics payload.
+    """
+    return Response(generate_latest(REGISTRY), media_type=CONTENT_TYPE_LATEST)

constellation_node_sdk/runtime/preflight.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from .config import NodeRuntimeConfig
+
+
+class PreflightFailure(RuntimeError):
+    """Raised when runtime configuration is not safe to start."""
+
+
+def run_preflight(config: NodeRuntimeConfig) -> None:
+    """
+    Validate runtime configuration relationships before starting a node runtime.
+    """
+    _validate_security_profile(config)
+    _validate_action_configuration(config)
+    _validate_attachment_configuration(config)
+    _validate_gate_configuration(config)
+    _validate_gate_ingress_authentication(config)
+
+
+def _validate_security_profile(config: NodeRuntimeConfig) -> None:
+    if config.dev_mode:
+        return
+
+    if not config.require_signature:
+        return
+
+    if config.signing_algorithm == "hmac-sha256":
+        if not config.signing_key:
+            raise PreflightFailure("hmac-sha256 requires signing_key when signatures are required")
+        return
+
+    if config.signing_algorithm == "ed25519":
+        if not config.signing_private_key:
+            raise PreflightFailure(
+                "ed25519 requires signing_private_key when signatures are required"
+            )
+        return
+
+    raise PreflightFailure(f"unsupported signing algorithm: {config.signing_algorithm}")
+
+
+def _validate_action_configuration(config: NodeRuntimeConfig) -> None:
+    allowed_actions = set(config.allowed_actions)
+    execute_allowed_actions = set(config.execute_allowed_actions)
+    known_actions = allowed_actions | execute_allowed_actions
+    required_idempotency = set(config.require_idempotency_for_actions)
+
+    if required_idempotency and not known_actions:
+        raise PreflightFailure(
+            "require_idempotency_for_actions is configured but allowed_actions and"
+            " execute_allowed_actions are both empty"
+        )
+
+    if not required_idempotency.issubset(known_actions):
+        invalid = sorted(required_idempotency - known_actions)
+        joined = ", ".join(invalid)
+        raise PreflightFailure(
+            "require_idempotency_for_actions contains actions not present"
+            f" in allowed_actions or execute_allowed_actions: {joined}"
+        )
+
+    if "response" in allowed_actions or "failure" in allowed_actions:
+        raise PreflightFailure(
+            "allowed_actions must list executable inbound actions only, not response packet types"
+        )
+
+
+def _validate_attachment_configuration(config: NodeRuntimeConfig) -> None:
+    if config.max_attachment_size_bytes > config.max_packet_bytes:
+        raise PreflightFailure("max_attachment_size_bytes must not exceed max_packet_bytes")
+
+    if config.max_attachments > 0 and not config.attachment_allowed_schemes:
+        raise PreflightFailure(
+            "attachment_allowed_schemes must be configured when attachments are enabled"
+        )
+
+
+def _validate_gate_configuration(config: NodeRuntimeConfig) -> None:
+    if config.gate_url is None:
+        return
+    if not (config.gate_url.startswith("http://") or config.gate_url.startswith("https://")):
+        raise PreflightFailure("gate_url must start with http:// or https://")
+
+
+def _validate_gate_ingress_authentication(config: NodeRuntimeConfig) -> None:
+    """
+    Gate-only ingress trust (provenance.resolved_by_gate, address.source_node,
+    provenance.route_kind) is caller-supplied and carries no authentication by
+    itself. If enforce_gate_only_ingress is relied upon without also requiring
+    a verified transport signature, any direct client can forge these claims
+    and bypass Gate-mediated routing entirely. Fail closed outside dev_mode.
+    """
+    if config.dev_mode or not config.enforce_gate_only_ingress:
+        return
+
+    execute_require_signature = (
+        config.execute_require_signature
+        if config.execute_require_signature is not None
+        else config.require_signature
+    )
+    if not execute_require_signature:
+        raise PreflightFailure(
+            "enforce_gate_only_ingress=true requires a verified signature on /v1/execute "
+            "(set require_signature=true or execute_require_signature=true); "
+            "unsigned Gate-only ingress trusts unauthenticated caller-supplied provenance"
+        )
+
+    if not config.enable_relay_route:
+        return
+
+    relay_require_signature = (
+        config.relay_require_signature
+        if config.relay_require_signature is not None
+        else config.require_signature
+    )
+    if not relay_require_signature:
+        raise PreflightFailure(
+            "enforce_gate_only_ingress=true requires a verified signature on /v1/relay "
+            "(set require_signature=true or relay_require_signature=true); "
+            "unsigned Gate-only ingress trusts unauthenticated caller-supplied provenance"
+        )

constellation_node_sdk/security/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from constellation_node_sdk.security.delegation import compute_delegation_proof
+from constellation_node_sdk.security.errors import (
+    SecurityError,
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportExpiredError,
+    TransportIntegrityError,
+    TransportNotYetValidError,
+    TransportValidationError,
+)
+from constellation_node_sdk.security.signing import recompute_transport_core, sign_transport_packet
+from constellation_node_sdk.security.validation import (
+    transport_packet_size_bytes,
+    validate_derived_transport_packet,
+    validate_transport_packet,
+)
+from constellation_node_sdk.security.verification import verify_transport_packet_signature
+
+__all__ = [
+    "SecurityError",
+    "TransportAuthenticationError",
+    "TransportAuthorizationError",
+    "TransportExpiredError",
+    "TransportIntegrityError",
+    "TransportNotYetValidError",
+    "TransportValidationError",
+    "compute_delegation_proof",
+    "recompute_transport_core",
+    "sign_transport_packet",
+    "transport_packet_size_bytes",
+    "validate_derived_transport_packet",
+    "validate_transport_packet",
+    "verify_transport_packet_signature",
+]

constellation_node_sdk/security/delegation.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from datetime import UTC, datetime
+from typing import Any
+
+from constellation_node_sdk.transport.hashing import canonical_json
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+def _coerce_bytes(value: str | bytes) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    normalized = value.strip()
+    try:
+        return base64.b64decode(normalized, validate=True)
+    except Exception:
+        return normalized.encode("utf-8")
+
+
+def compute_delegation_proof(
+    *,
+    packet: TransportPacket,
+    delegator: str,
+    delegatee: str,
+    scope: tuple[str, ...],
+    granted_at: datetime,
+    key: bytes | str,
+    expires_at: datetime | None = None,
+    constraints: dict[str, Any] | None = None,
+) -> str:
+    """
+    Compute an HMAC proof for a delegation grant.
+
+    Delegation proofs are bound to:
+    - packet_id
+    - transport_hash
+    - delegator/delegatee
+    - scope
+    - grant time
+    - optional expiry/constraints
+    """
+    raw_key = _coerce_bytes(key)
+    normalized_scope = tuple(item.strip().lower() for item in scope if item.strip())
+    message = {
+        "packet_id": str(packet.header.packet_id),
+        "transport_hash": packet.security.transport_hash,
+        "delegator": delegator.strip().lower(),
+        "delegatee": delegatee.strip().lower(),
+        "scope": list(normalized_scope),
+        "granted_at": granted_at.astimezone(UTC).isoformat(),
+        "expires_at": expires_at.astimezone(UTC).isoformat() if expires_at else None,
+        "constraints": constraints or {},
+    }
+    return hmac.new(raw_key, canonical_json(message), hashlib.sha256).hexdigest()