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

constellation_node_sdk/__init__.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from constellation_node_sdk.gate import (
+    GateClient,
+    GateClientConfig,
+    GateRegistrationConfig,
+    assert_gate_only_destination,
+    assert_local_node_identity,
+    assert_node_origin_packet,
+    build_registration_payload,
+    get_gate_client_config_from_env,
+    get_gate_registration_config_from_env,
+    load_node_spec,
+    register_from_env,
+    register_with_gate,
+    validate_outbound_gate_packet,
+)
+from constellation_node_sdk.runtime import (
+    LifecycleHook,
+    NodeRuntimeConfig,
+    NoOpLifecycle,
+    PreflightFailure,
+    clear_handlers,
+    create_error_transport_packet,
+    create_node_app,
+    execute_transport_packet,
+    get_handler,
+    get_runtime_config,
+    register_handler,
+    registered_actions,
+    run_preflight,
+)
+from constellation_node_sdk.security import (
+    recompute_transport_core,
+    sign_transport_packet,
+    validate_derived_transport_packet,
+    validate_transport_packet,
+    verify_transport_packet_signature,
+)
+from constellation_node_sdk.transport import (
+    DelegationLink,
+    RoutingProvenance,
+    TenantContext,
+    TransportAddress,
+    TransportAttachment,
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportError,
+    TransportExpiredError,
+    TransportGovernance,
+    TransportHeader,
+    TransportHop,
+    TransportIntegrityError,
+    TransportLineage,
+    TransportNotYetValidError,
+    TransportPacket,
+    TransportSecurity,
+    TransportValidationError,
+    canonical_json,
+    compute_payload_hash,
+    compute_transport_hash,
+    create_transport_packet,
+    ensure_tenant_context,
+    utc_now,
+)
+
+__all__ = [
+    "DelegationLink",
+    "GateClient",
+    "GateClientConfig",
+    "GateRegistrationConfig",
+    "LifecycleHook",
+    "NoOpLifecycle",
+    "NodeRuntimeConfig",
+    "PreflightFailure",
+    "RoutingProvenance",
+    "TenantContext",
+    "TransportAddress",
+    "TransportAttachment",
+    "TransportAuthenticationError",
+    "TransportAuthorizationError",
+    "TransportError",
+    "TransportExpiredError",
+    "TransportGovernance",
+    "TransportHeader",
+    "TransportHop",
+    "TransportIntegrityError",
+    "TransportLineage",
+    "TransportNotYetValidError",
+    "TransportPacket",
+    "TransportSecurity",
+    "TransportValidationError",
+    "assert_gate_only_destination",
+    "assert_local_node_identity",
+    "assert_node_origin_packet",
+    "build_registration_payload",
+    "canonical_json",
+    "clear_handlers",
+    "compute_payload_hash",
+    "compute_transport_hash",
+    "create_error_transport_packet",
+    "create_node_app",
+    "create_transport_packet",
+    "ensure_tenant_context",
+    "execute_transport_packet",
+    "get_gate_client_config_from_env",
+    "get_gate_registration_config_from_env",
+    "get_handler",
+    "get_runtime_config",
+    "load_node_spec",
+    "recompute_transport_core",
+    "register_from_env",
+    "register_handler",
+    "register_with_gate",
+    "registered_actions",
+    "run_preflight",
+    "sign_transport_packet",
+    "utc_now",
+    "validate_derived_transport_packet",
+    "validate_outbound_gate_packet",
+    "validate_transport_packet",
+    "verify_transport_packet_signature",
+]

constellation_node_sdk/gate/__init__.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from constellation_node_sdk.gate.client import GateClient
+from constellation_node_sdk.gate.config import (
+    GateClientConfig,
+    GateRegistrationConfig,
+    get_gate_client_config_from_env,
+    get_gate_registration_config_from_env,
+)
+from constellation_node_sdk.gate.errors import (
+    GateClientError,
+    GatePolicyError,
+    GateRegistrationError,
+    GateResponseError,
+)
+from constellation_node_sdk.gate.policy import (
+    assert_gate_only_destination,
+    assert_local_node_identity,
+    assert_node_origin_packet,
+    validate_outbound_gate_packet,
+)
+from constellation_node_sdk.gate.registration import (
+    build_registration_payload,
+    load_node_spec,
+    register_from_env,
+    register_with_gate,
+)
+
+__all__ = [
+    "GateClient",
+    "GateClientConfig",
+    "GateClientError",
+    "GatePolicyError",
+    "GateRegistrationConfig",
+    "GateRegistrationError",
+    "GateResponseError",
+    "assert_gate_only_destination",
+    "assert_local_node_identity",
+    "assert_node_origin_packet",
+    "build_registration_payload",
+    "get_gate_client_config_from_env",
+    "get_gate_registration_config_from_env",
+    "load_node_spec",
+    "register_from_env",
+    "register_with_gate",
+    "validate_outbound_gate_packet",
+]

constellation_node_sdk/gate/client.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+
+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.packet import TransportPacket
+
+from .config import GateClientConfig
+from .policy import validate_outbound_gate_packet
+
+
+class GateClient:
+    """
+    Canonical Gate-only transport client for nodes.
+
+    This client is the only allowed outbound inter-node transport surface.
+    It never accepts an arbitrary peer URL.
+    """
+
+    def __init__(self, config: GateClientConfig) -> None:
+        self._config = config
+
+    @property
+    def gate_url(self) -> str:
+        return self._config.gate_url
+
+    def _transport_key_resolver(
+        self,
+    ) -> Callable[[str | None], str | bytes | None] | Mapping[str, str | bytes] | None:
+        if not self._config.verifying_keys and self._config.signing_key is None:
+            return None
+        return self._config.resolve_verifying_key
+
+    def _maybe_sign(self, packet: TransportPacket) -> TransportPacket:
+        if self._config.signing_key is None:
+            return packet
+        if self._config.signing_key_id is None or self._config.signing_algorithm is None:
+            raise ValueError(
+                "signing_key_id and signing_algorithm are required when signing_key is configured"
+            )
+        return sign_transport_packet(
+            packet,
+            key=self._config.signing_key,
+            key_id=self._config.signing_key_id,
+            algorithm=self._config.signing_algorithm,
+        )
+
+    def _validate_outbound(self, packet: TransportPacket) -> None:
+        validate_outbound_gate_packet(
+            packet,
+            local_node=self._config.local_node,
+            gate_node_name=self._config.allowed_gate_destination,
+        )
+        validate_transport_packet(
+            packet,
+            key_resolver=self._transport_key_resolver(),
+            require_signature=self._config.require_signature,
+            dev_mode=not self._config.require_signature,
+            verify_hop_signatures=self._config.verify_hop_signatures,
+        )
+
+    def _validate_inbound_response(self, packet: TransportPacket) -> None:
+        validate_transport_packet(
+            packet,
+            key_resolver=self._transport_key_resolver(),
+            require_signature=self._config.verify_response_signatures,
+            dev_mode=not self._config.verify_response_signatures,
+            verify_hop_signatures=self._config.verify_hop_signatures,
+        )
+
+    async def send_to_gate(self, packet: TransportPacket) -> TransportPacket:
+        """
+        Send a canonical TransportPacket to Gate and decode a canonical TransportPacket response.
+        """
+        self._validate_outbound(packet)
+        signed_packet = self._maybe_sign(packet)
+
+        async with httpx.AsyncClient(timeout=self._config.timeout_seconds) as client:
+            response = await client.post(
+                f"{self._config.gate_url}/v1/execute",
+                json=signed_packet.model_dump_json_dict(),
+                headers={"Content-Type": "application/json"},
+            )
+
+        response.raise_for_status()
+        body = response.json()
+        if not isinstance(body, dict):
+            raise ValueError("Gate response body must be a JSON object")
+
+        response_packet = TransportPacket.model_validate(body)
+        self._validate_inbound_response(response_packet)
+        return response_packet
+
+    async def health(self) -> dict[str, Any]:
+        """
+        Query Gate health endpoint.
+        """
+        async with httpx.AsyncClient(timeout=self._config.timeout_seconds) as client:
+            response = await client.get(f"{self._config.gate_url}/v1/health")
+        response.raise_for_status()
+        body = response.json()
+        if not isinstance(body, dict):
+            raise ValueError("Gate health response must be a JSON object")
+        return body

constellation_node_sdk/gate/config.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import os
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+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"}
+
+
+class GateClientConfig(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    gate_url: str
+    local_node: str
+    timeout_seconds: float = Field(default=30.0, gt=0.0)
+    require_signature: bool = False
+    signing_key: str | bytes | None = None
+    signing_key_id: str | None = None
+    signing_algorithm: str | None = None
+    verify_response_signatures: bool = False
+    verifying_keys: dict[str, str] = Field(default_factory=dict)
+    verify_hop_signatures: bool = False
+    allowed_gate_destination: str = "gate"
+
+    @field_validator("gate_url")
+    @classmethod
+    def validate_gate_url(cls, value: str) -> str:
+        normalized = value.strip().rstrip("/")
+        if not normalized:
+            raise ValueError("gate_url must not be empty")
+        if not (normalized.startswith("http://") or normalized.startswith("https://")):
+            raise ValueError("gate_url must start with http:// or https://")
+        return normalized
+
+    @field_validator("local_node", "allowed_gate_destination")
+    @classmethod
+    def validate_node_fields(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if not normalized:
+            raise ValueError("node fields must not be empty")
+        return normalized
+
+    @field_validator("signing_key_id", "signing_algorithm")
+    @classmethod
+    def validate_optional_strings(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("optional string fields 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
+
+    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
+            and self.signing_key is not None
+        ):
+            return self.signing_key
+        return None
+
+
+class GateRegistrationConfig(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    gate_url: str
+    admin_token: str | None = None
+    spec_path: str = "engine/spec.yaml"
+    registration_enabled: bool = True
+    retries: int = Field(default=3, ge=1)
+    overwrite: bool = True
+
+    @field_validator("gate_url")
+    @classmethod
+    def validate_gate_url(cls, value: str) -> str:
+        normalized = value.strip().rstrip("/")
+        if not normalized:
+            raise ValueError("gate_url must not be empty")
+        if not (normalized.startswith("http://") or normalized.startswith("https://")):
+            raise ValueError("gate_url must start with http:// or https://")
+        return normalized
+
+    @field_validator("admin_token", "spec_path")
+    @classmethod
+    def validate_optional_strings(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("optional string fields must not be blank")
+        return normalized
+
+
+def get_gate_client_config_from_env() -> GateClientConfig:
+    gate_url = os.getenv("GATE_URL", "").strip()
+    if not gate_url:
+        raise ValueError("GATE_URL is required")
+
+    local_node = os.getenv("L9_NODE_NAME", "unknown-node").strip().lower() or "unknown-node"
+    signing_key = os.getenv("L9_SIGNING_KEY") or os.getenv("L9_SIGNING_SECRET")
+    signing_key_id = os.getenv("L9_SIGNING_KEY_ID")
+    signing_algorithm = os.getenv("L9_SIGNING_ALGORITHM")
+    verify_response_signatures = _env_bool("L9_REQUIRE_SIGNATURE", False)
+
+    return GateClientConfig(
+        gate_url=gate_url,
+        local_node=local_node,
+        timeout_seconds=float(os.getenv("GATE_CLIENT_TIMEOUT_SECONDS", "30.0")),
+        require_signature=_env_bool("L9_REQUIRE_SIGNATURE", False),
+        signing_key=signing_key,
+        signing_key_id=signing_key_id,
+        signing_algorithm=signing_algorithm,
+        verify_response_signatures=verify_response_signatures,
+        verifying_keys={},
+        verify_hop_signatures=_env_bool("L9_VERIFY_HOP_SIGNATURES", False),
+        allowed_gate_destination=os.getenv("GATE_ALLOWED_DESTINATION", "gate"),
+    )
+
+
+def get_gate_registration_config_from_env() -> GateRegistrationConfig:
+    gate_url = os.getenv("GATE_URL", "").strip()
+    if not gate_url:
+        raise ValueError("GATE_URL is required")
+
+    return GateRegistrationConfig(
+        gate_url=gate_url,
+        admin_token=os.getenv("GATE_ADMIN_TOKEN") or None,
+        spec_path=os.getenv("GATE_NODE_SPEC_PATH", "engine/spec.yaml"),
+        registration_enabled=_env_bool("GATE_REGISTRATION_ENABLED", True),
+        retries=int(os.getenv("GATE_REGISTER_RETRIES", "3")),
+        overwrite=_env_bool("GATE_REGISTER_OVERWRITE", True),
+    )

constellation_node_sdk/gate/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class GateClientError(Exception):
+    """Base exception for Gate client failures."""
+
+
+class GatePolicyError(GateClientError):
+    """Raised when an outbound packet violates Gate-only routing policy."""
+
+
+class GateResponseError(GateClientError):
+    """Raised when Gate returns an invalid or non-canonical response."""
+
+
+class GateRegistrationError(GateClientError):
+    """Raised when Gate registration cannot be completed safely."""

constellation_node_sdk/gate/policy.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+def assert_node_origin_packet(packet: TransportPacket) -> None:
+    """
+    Require that a packet sent through the Gate client is node-originated.
+
+    External clients should speak to Gate directly without going through the node SDK.
+    """
+    source = packet.address.source_node.strip().lower()
+    if source in {"", "client"}:
+        raise ValueError(
+            "Gate client only accepts node-originated packets with non-client source_node"
+        )
+
+    provenance_origin = packet.provenance.origin_kind.strip().lower()
+    if provenance_origin != "node":
+        raise ValueError("Gate client requires packet.provenance.origin_kind == 'node'")
+
+
+def assert_gate_only_destination(packet: TransportPacket, *, gate_node_name: str = "gate") -> None:
+    """
+    Enforce the architectural rule that node-originated packets target Gate only.
+    """
+    normalized_gate = gate_node_name.strip().lower()
+    destination = packet.address.destination_node.strip().lower()
+
+    if destination != normalized_gate:
+        raise ValueError(
+            f"node-originated packets must target {normalized_gate!r}, got {destination!r}"
+        )
+
+    requested_action = packet.provenance.requested_action.strip().lower()
+    if requested_action != packet.header.action:
+        raise ValueError("packet.provenance.requested_action must match packet.header.action")
+
+
+def assert_local_node_identity(packet: TransportPacket, *, local_node: str) -> None:
+    """
+    Ensure the packet source matches the local runtime node identity.
+    """
+    normalized_local = local_node.strip().lower()
+    if packet.address.source_node != normalized_local:
+        raise ValueError(
+            f"packet source_node {packet.address.source_node!r} does not match"
+            f" local node {normalized_local!r}"
+        )
+
+    original_source = packet.provenance.original_source_node
+    if original_source is not None and original_source != normalized_local:
+        raise ValueError(
+            "packet.provenance.original_source_node must match local node"
+            " for node-originated packets"
+        )
+
+
+def validate_outbound_gate_packet(
+    packet: TransportPacket,
+    *,
+    local_node: str,
+    gate_node_name: str = "gate",
+) -> None:
+    """
+    Apply the full outbound routing policy for the Gate client.
+    """
+    assert_node_origin_packet(packet)
+    assert_local_node_identity(packet, local_node=local_node)
+    assert_gate_only_destination(packet, gate_node_name=gate_node_name)

constellation_node_sdk/gate/registration.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import httpx
+import yaml
+
+from .config import GateRegistrationConfig, get_gate_registration_config_from_env
+
+_DEFAULT_RETRY_BASE_SECONDS = 1.0
+
+
+def load_node_spec(spec_path: str) -> dict[str, Any]:
+    """
+    Load node spec.yaml and require a top-level mapping.
+    """
+    path = Path(spec_path)
+    if not path.exists():
+        raise FileNotFoundError(f"node spec not found: {path.resolve()}")
+
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError(f"node spec must be a YAML mapping: {path}")
+    return raw
+
+
+def build_registration_payload(spec: dict[str, Any]) -> dict[str, Any]:
+    """
+    Convert spec.yaml into Gate admin registration payload.
+
+    Required:
+    - node.id
+    - node.actions
+    """
+    node = spec.get("node", {})
+    if not isinstance(node, dict) or not node:
+        raise ValueError("spec.yaml missing required node block")
+
+    node_id = str(node.get("id", "")).strip().lower()
+    if not node_id:
+        raise ValueError("spec.yaml node.id is required")
+
+    actions_raw = node.get("actions", [])
+    if not isinstance(actions_raw, list) or not actions_raw:
+        raise ValueError(f"spec.yaml node.actions must not be empty (node: {node_id})")
+
+    actions = [str(action).strip().lower() for action in actions_raw if str(action).strip()]
+    if not actions:
+        raise ValueError(
+            f"spec.yaml node.actions must contain at least one non-blank action (node: {node_id})"
+        )
+
+    internal_url = str(node.get("internal_url", f"http://{node_id}:8000")).strip().rstrip("/")
+    if not internal_url:
+        raise ValueError("spec.yaml node.internal_url must not be blank")
+
+    return {
+        node_id: {
+            "internal_url": internal_url,
+            "supported_actions": actions,
+            "priority_class": str(node.get("priority_class", "P2")).strip() or "P2",
+            "max_concurrent": int(node.get("max_concurrent", 50)),
+            "health_endpoint": str(node.get("health_endpoint", "/v1/health")).strip()
+            or "/v1/health",
+            "timeout_ms": int(node.get("timeout_ms", 30000)),
+            "metadata": {
+                "version": str(node.get("version", "1.0.0")).strip() or "1.0.0",
+                "type": str(node.get("type", "custom")).strip() or "custom",
+                "generated_by": "constellation-node-sdk",
+            },
+        }
+    }
+
+
+async def register_with_gate(
+    *,
+    gate_url: str,
+    admin_token: str | None = None,
+    spec_path: str,
+    retries: int = 3,
+    overwrite: bool = True,
+) -> bool:
+    """
+    Register the current node with Gate via POST /v1/admin/register.
+
+    Returns True on success, False on rejection or after retry exhaustion.
+    Registration failure is intentionally non-fatal for node startup.
+    """
+    try:
+        spec = load_node_spec(spec_path)
+        payload = build_registration_payload(spec)
+    except (FileNotFoundError, ValueError):
+        return False
+
+    _node_id = next(iter(payload))  # noqa: F841 — used for future logging
+    url = f"{gate_url.rstrip('/')}/v1/admin/register"
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if admin_token:
+        headers["X-Admin-Token"] = admin_token
+    params = {"overwrite": "true" if overwrite else "false"}
+
+    for attempt in range(1, retries + 1):
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.post(
+                    url,
+                    json=payload,
+                    headers=headers,
+                    params=params,
+                )
+
+            if response.status_code == 200:
+                return True
+
+            if response.status_code in {400, 401, 403, 409, 422}:
+                return False
+
+        except httpx.TransportError:
+            pass
+
+        if attempt < retries:
+            backoff = _DEFAULT_RETRY_BASE_SECONDS * (2 ** (attempt - 1))
+            await asyncio.sleep(backoff)
+
+    return False
+
+
+async def register_from_env() -> bool:
+    """
+    Convenience wrapper for Gate registration using environment-derived config.
+    """
+    config: GateRegistrationConfig = get_gate_registration_config_from_env()
+    if not config.registration_enabled:
+        return False
+
+    return await register_with_gate(
+        gate_url=config.gate_url,
+        admin_token=config.admin_token,
+        spec_path=config.spec_path,
+        retries=config.retries,
+        overwrite=config.overwrite,
+    )

constellation_node_sdk/orchestrator/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__all__: list[str] = []