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

constellation_node_sdk/security/errors.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from constellation_node_sdk.transport.errors import (
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportExpiredError,
+    TransportIntegrityError,
+    TransportNotYetValidError,
+    TransportValidationError,
+)
+
+
+class SecurityError(Exception):
+    """Base exception for the SDK security layer."""
+
+
+__all__ = [
+    "SecurityError",
+    "TransportAuthenticationError",
+    "TransportAuthorizationError",
+    "TransportExpiredError",
+    "TransportIntegrityError",
+    "TransportNotYetValidError",
+    "TransportValidationError",
+]

constellation_node_sdk/security/signing.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.serialization import load_pem_private_key
+
+from constellation_node_sdk.transport.hashing import compute_payload_hash, compute_transport_hash
+from constellation_node_sdk.transport.models import TransportSecurity
+from constellation_node_sdk.transport.packet import TransportPacket
+
+from .errors import TransportAuthenticationError
+
+
+def _coerce_bytes(value: str | bytes) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    normalized = value.strip()
+    if normalized.startswith("-----BEGIN"):
+        return normalized.encode("utf-8")
+    try:
+        return base64.b64decode(normalized, validate=True)
+    except Exception:
+        return normalized.encode("utf-8")
+
+
+def _load_ed25519_private_key(raw: bytes) -> Ed25519PrivateKey:
+    if raw.startswith(b"-----BEGIN"):
+        loaded = load_pem_private_key(raw, password=None)
+        if not isinstance(loaded, Ed25519PrivateKey):
+            raise TransportAuthenticationError("PEM private key is not Ed25519")
+        return loaded
+    if len(raw) == 32:
+        return Ed25519PrivateKey.from_private_bytes(raw)
+    raise TransportAuthenticationError("unsupported ed25519 private key format")
+
+
+def recompute_transport_core(packet: TransportPacket) -> TransportPacket:
+    """
+    Recompute payload_hash and transport_hash while preserving hop_trace.
+
+    hop_trace is intentionally excluded from transport_hash.
+    Any existing packet signature is cleared and must be re-applied by the caller.
+    """
+    payload_hash = compute_payload_hash(packet.payload)
+
+    provisional = packet.model_copy(
+        update={
+            "security": packet.security.model_copy(
+                update={
+                    "payload_hash": payload_hash,
+                    "transport_hash": "0" * 64,
+                    "signature": None,
+                    "signature_algorithm": None,
+                    "signing_key_id": None,
+                }
+            )
+        }
+    )
+
+    transport_hash = compute_transport_hash(provisional)
+    finalized = provisional.model_copy(
+        update={
+            "security": provisional.security.model_copy(
+                update={
+                    "transport_hash": transport_hash,
+                }
+            )
+        }
+    )
+
+    return TransportPacket.model_validate(finalized)
+
+
+def sign_transport_packet(
+    packet: TransportPacket,
+    *,
+    key: bytes | str,
+    key_id: str,
+    algorithm: str,
+) -> TransportPacket:
+    """
+    Sign a transport packet over its stable transport_hash.
+
+    The packet's hop_trace is preserved, but is not included in the signature domain.
+    """
+    normalized_algorithm = algorithm.strip().lower()
+    raw_key = _coerce_bytes(key)
+    normalized = recompute_transport_core(packet)
+
+    if normalized_algorithm == "hmac-sha256":
+        signature = hmac.new(
+            raw_key,
+            normalized.security.transport_hash.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+    elif normalized_algorithm == "ed25519":
+        private_key = _load_ed25519_private_key(raw_key)
+        signature = private_key.sign(normalized.security.transport_hash.encode("utf-8")).hex()
+    else:
+        raise TransportAuthenticationError(
+            f"unsupported signature algorithm: {normalized_algorithm}"
+        )
+
+    signed = normalized.model_copy(
+        update={
+            "security": TransportSecurity(
+                payload_hash=normalized.security.payload_hash,
+                transport_hash=normalized.security.transport_hash,
+                signature=signature,
+                signature_algorithm=normalized_algorithm,
+                signing_key_id=key_id.strip(),
+                classification=normalized.security.classification,
+                encryption_status=normalized.security.encryption_status,
+                pii_fields=normalized.security.pii_fields,
+            )
+        }
+    )
+    return TransportPacket.model_validate(signed)

constellation_node_sdk/security/validation.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import ipaddress
+import json
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime, timedelta
+from urllib.parse import urlparse
+
+from constellation_node_sdk.security.verification import verify_transport_packet_signature
+from constellation_node_sdk.transport.errors import (
+    PacketSizeError,
+    SchemaVersionError,
+    TenantMutationError,
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportExpiredError,
+    TransportIntegrityError,
+    TransportNotYetValidError,
+    TransportValidationError,
+)
+from constellation_node_sdk.transport.hop_trace import validate_hop_trace
+from constellation_node_sdk.transport.packet import TransportPacket
+from constellation_node_sdk.transport.tenant import assert_tenant_immutable
+
+
+def transport_packet_size_bytes(packet: TransportPacket) -> int:
+    return len(
+        json.dumps(
+            packet.model_dump_json_dict(),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+    )
+
+
+def validate_derived_transport_packet(parent: TransportPacket, child: TransportPacket) -> None:
+    try:
+        assert_tenant_immutable(parent.tenant, child.tenant)
+    except TenantMutationError:
+        raise
+    except Exception as exc:
+        raise TenantMutationError(str(exc)) from exc
+
+    if child.lineage.parent_id != parent.header.packet_id:
+        raise TransportValidationError("derived packet parent_id mismatch")
+    if child.lineage.root_id != parent.lineage.root_id:
+        raise TransportValidationError("derived packet root_id mismatch")
+    if child.lineage.generation != parent.lineage.generation + 1:
+        raise TransportValidationError("derived packet generation must increment by 1")
+
+
+def validate_transport_packet(
+    packet: TransportPacket,
+    *,
+    key_resolver: Callable[[str | None], str | bytes | None]
+    | Mapping[str, str | bytes]
+    | str
+    | bytes
+    | None = None,
+    require_signature: bool = False,
+    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,
+    allowed_clock_skew_seconds: int = 30,
+    local_node: str | None = None,
+    allowed_actions: tuple[str, ...] | None = None,
+    allowed_packet_types: tuple[str, ...] | None = None,
+    required_idempotency_actions: tuple[str, ...] | None = None,
+    replay_enabled: bool = True,
+    now: datetime | None = None,
+    dev_mode: bool = False,
+    verify_hop_signatures: bool = False,
+    hop_key_resolver: Callable[[str | None], str | bytes | None]
+    | Mapping[str, str | bytes]
+    | str
+    | bytes
+    | None = None,
+    require_monotonic_hop_timestamps: bool = True,
+) -> None:
+    current_time = (now or datetime.now(UTC)).astimezone(UTC)
+
+    if packet.header.schema_version != "1.0":
+        raise SchemaVersionError(f"unsupported schema_version: {packet.header.schema_version}")
+
+    if allowed_packet_types is not None and packet.header.packet_type not in set(
+        allowed_packet_types
+    ):
+        raise TransportAuthorizationError(f"packet_type not allowed: {packet.header.packet_type}")
+
+    if allowed_actions is not None and packet.header.action not in set(allowed_actions):
+        raise TransportAuthorizationError(f"action not allowed: {packet.header.action}")
+
+    if local_node is not None and packet.address.destination_node != local_node.strip().lower():
+        raise TransportAuthorizationError("packet destination does not match this node")
+
+    if packet.header.created_at > current_time + timedelta(seconds=allowed_clock_skew_seconds):
+        raise TransportValidationError("packet created_at exceeds allowed clock skew")
+
+    if transport_packet_size_bytes(packet) > max_packet_bytes:
+        raise PacketSizeError("packet exceeds maximum allowed size")
+
+    if len(packet.hop_trace) > max_hop_depth:
+        raise TransportValidationError("hop trace exceeds maximum depth")
+
+    if len(packet.delegation_chain) > max_delegation_depth:
+        raise TransportValidationError("delegation chain exceeds maximum depth")
+
+    if len(packet.attachments) > max_attachments:
+        raise TransportValidationError("attachment count exceeds maximum")
+
+    for attachment in packet.attachments:
+        if attachment.size_bytes > max_attachment_size_bytes:
+            raise TransportValidationError("attachment exceeds maximum allowed size")
+        _validate_attachment_uri(
+            attachment.uri,
+            allowed_schemes=allowed_attachment_schemes,
+            allow_private_hosts=allow_private_attachment_hosts,
+        )
+
+    if not packet.security.payload_hash or not packet.security.transport_hash:
+        raise TransportIntegrityError("packet hashes are missing")
+
+    if packet.header.not_before is not None and current_time < packet.header.not_before:
+        raise TransportNotYetValidError("packet not valid yet")
+
+    if packet.header.expires_at is not None and current_time > packet.header.expires_at:
+        raise TransportExpiredError("packet TTL exceeded")
+
+    if packet.header.packet_type == "replay_request":
+        if not packet.header.replay_mode:
+            raise TransportValidationError("replay_request packets must set replay_mode=true")
+        if not replay_enabled:
+            raise TransportAuthorizationError("replay is disabled on this service")
+
+    if packet.header.replay_mode and packet.header.packet_type != "replay_request":
+        raise TransportValidationError("replay_mode is only permitted for replay_request packets")
+
+    if required_idempotency_actions and packet.header.action in set(required_idempotency_actions):
+        if not packet.header.idempotency_key:
+            raise TransportValidationError("idempotency_key required for this action")
+
+    if "GDPR" in packet.governance.compliance_tags and not packet.governance.data_subject_id:
+        raise TransportValidationError("GDPR packets require data_subject_id")
+
+    if (
+        packet.security.classification == "restricted"
+        and packet.governance.audit_required is not True
+    ):
+        raise TransportValidationError("restricted packets must set audit_required=true")
+
+    _validate_delegation_chain(packet, now=current_time)
+
+    if packet.security.signature is None:
+        if (require_signature or packet.security.classification == "restricted") and not dev_mode:
+            raise TransportAuthenticationError("signature required but not present")
+    else:
+        if not (dev_mode and key_resolver is None):
+            if not verify_transport_packet_signature(packet, key_resolver=key_resolver):
+                raise TransportAuthenticationError("invalid transport signature")
+
+    validate_hop_trace(
+        packet,
+        verify_hop_signatures=verify_hop_signatures,
+        hop_key_resolver=hop_key_resolver,
+        require_monotonic_timestamps=require_monotonic_hop_timestamps,
+    )
+
+
+def _validate_delegation_chain(packet: TransportPacket, *, now: datetime) -> None:
+    previous_scope: set[str] | None = None
+
+    for index, link in enumerate(packet.delegation_chain):
+        current_scope = set(link.scope)
+
+        if previous_scope is not None and not current_scope.issubset(previous_scope):
+            raise TransportAuthorizationError("delegation scope escalation detected")
+
+        if link.expires_at is not None and now > link.expires_at.astimezone(UTC):
+            raise TransportAuthorizationError("delegation link expired")
+
+        if index == len(packet.delegation_chain) - 1 and packet.header.packet_type == "delegation":
+            if packet.header.action not in current_scope:
+                raise TransportAuthorizationError(
+                    "delegated packet action not permitted by last delegation scope"
+                )
+            if packet.address.destination_node != link.delegatee:
+                raise TransportAuthorizationError(
+                    "delegated packet destination does not match last delegation target"
+                )
+
+        previous_scope = current_scope
+
+
+def _validate_attachment_uri(
+    uri: str, *, allowed_schemes: tuple[str, ...], allow_private_hosts: bool
+) -> None:
+    parsed = urlparse(uri)
+    scheme = parsed.scheme.lower()
+
+    if not scheme:
+        raise TransportValidationError("attachment uri must include a scheme")
+    if allowed_schemes and scheme not in set(allowed_schemes):
+        raise TransportValidationError(f"attachment scheme not allowed: {scheme}")
+    if scheme in {"file", "ftp"}:
+        raise TransportValidationError(f"attachment scheme not allowed: {scheme}")
+
+    hostname = parsed.hostname
+    if hostname is None:
+        if scheme in {"https", "http"}:
+            raise TransportValidationError("http(s) attachment uri must include a host")
+        return
+
+    normalized_host = hostname.lower()
+    if normalized_host in {"localhost", "metadata.google.internal"}:
+        raise TransportValidationError("attachment host not allowed")
+
+    try:
+        host_ip = ipaddress.ip_address(normalized_host)
+    except ValueError:
+        return
+
+    if not allow_private_hosts and (
+        host_ip.is_private or host_ip.is_loopback or host_ip.is_link_local
+    ):
+        raise TransportValidationError("private attachment hosts are not allowed")

constellation_node_sdk/security/verification.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from collections.abc import Callable, Mapping
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from constellation_node_sdk.transport.errors import TransportAuthenticationError
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+def _coerce_bytes(value: str | bytes) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    normalized = value.strip()
+    if normalized.startswith("-----BEGIN"):
+        return normalized.encode("utf-8")
+    try:
+        return base64.b64decode(normalized, validate=True)
+    except Exception:
+        return normalized.encode("utf-8")
+
+
+def _resolve_key(
+    key_resolver: Callable[[str | None], str | bytes | None]
+    | Mapping[str, str | bytes]
+    | str
+    | bytes
+    | None,
+    key_id: str | None,
+) -> bytes | None:
+    if key_resolver is None:
+        return None
+    if isinstance(key_resolver, (bytes, str)):
+        return _coerce_bytes(key_resolver)
+    if callable(key_resolver):
+        value = key_resolver(key_id)
+    else:
+        if key_id is None:
+            return None
+        value = key_resolver.get(key_id)
+    if value is None:
+        return None
+    return _coerce_bytes(value)
+
+
+def _load_ed25519_public_key(raw: bytes) -> Ed25519PublicKey:
+    if raw.startswith(b"-----BEGIN"):
+        loaded = load_pem_public_key(raw)
+        if not isinstance(loaded, Ed25519PublicKey):
+            raise TransportAuthenticationError("PEM public key is not Ed25519")
+        return loaded
+    if len(raw) == 32:
+        return Ed25519PublicKey.from_public_bytes(raw)
+    raise TransportAuthenticationError("unsupported ed25519 public key format")
+
+
+def verify_transport_packet_signature(
+    packet: TransportPacket,
+    *,
+    key_resolver: Callable[[str | None], str | bytes | None]
+    | Mapping[str, str | bytes]
+    | str
+    | bytes
+    | None,
+) -> bool:
+    """
+    Verify the packet signature against packet.security.transport_hash.
+
+    Returns False for unsigned packets.
+    Raises TransportAuthenticationError for key resolution or verification failures.
+    """
+    if packet.security.signature is None or packet.security.signature_algorithm is None:
+        return False
+
+    key = _resolve_key(key_resolver, packet.security.signing_key_id)
+    if key is None:
+        raise TransportAuthenticationError(
+            "no verifying key available for transport signature verification"
+        )
+
+    if packet.security.signature_algorithm == "hmac-sha256":
+        expected = hmac.new(
+            key,
+            packet.security.transport_hash.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        return hmac.compare_digest(packet.security.signature, expected)
+
+    if packet.security.signature_algorithm == "ed25519":
+        public_key = _load_ed25519_public_key(key)
+        try:
+            public_key.verify(
+                bytes.fromhex(packet.security.signature),
+                packet.security.transport_hash.encode("utf-8"),
+            )
+            return True
+        except (ValueError, InvalidSignature) as exc:
+            raise TransportAuthenticationError("invalid ed25519 transport signature") from exc
+
+    raise TransportAuthenticationError(
+        f"unsupported signature algorithm: {packet.security.signature_algorithm}"
+    )

constellation_node_sdk/transport/__init__.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from constellation_node_sdk.transport.errors import (
+    PacketSizeError,
+    SchemaVersionError,
+    TenantMutationError,
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportError,
+    TransportExpiredError,
+    TransportIntegrityError,
+    TransportNotYetValidError,
+    TransportValidationError,
+)
+from constellation_node_sdk.transport.hashing import (
+    canonical_json,
+    compute_payload_hash,
+    compute_transport_hash,
+)
+from constellation_node_sdk.transport.hop_trace import (
+    compute_hop_hash,
+    last_hop_hash,
+    make_dispatch_hop,
+    make_execution_hop,
+    make_ingress_hop,
+    make_response_hop,
+    sign_hop,
+    validate_hop_trace,
+    verify_hop_signature,
+)
+from constellation_node_sdk.transport.models import (
+    DelegationLink,
+    TransportAddress,
+    TransportAttachment,
+    TransportGovernance,
+    TransportHeader,
+    TransportHop,
+    TransportLineage,
+    TransportSecurity,
+    utc_now,
+)
+from constellation_node_sdk.transport.packet import TransportPacket, create_transport_packet
+from constellation_node_sdk.transport.provenance import RoutingProvenance
+from constellation_node_sdk.transport.tenant import (
+    TenantContext,
+    assert_tenant_immutable,
+    ensure_tenant_context,
+)
+
+__all__ = [
+    "DelegationLink",
+    "PacketSizeError",
+    "RoutingProvenance",
+    "SchemaVersionError",
+    "TenantContext",
+    "TenantMutationError",
+    "TransportAddress",
+    "TransportAttachment",
+    "TransportAuthenticationError",
+    "TransportAuthorizationError",
+    "TransportError",
+    "TransportExpiredError",
+    "TransportGovernance",
+    "TransportHeader",
+    "TransportHop",
+    "TransportIntegrityError",
+    "TransportLineage",
+    "TransportNotYetValidError",
+    "TransportPacket",
+    "TransportSecurity",
+    "TransportValidationError",
+    "assert_tenant_immutable",
+    "canonical_json",
+    "compute_hop_hash",
+    "compute_payload_hash",
+    "compute_transport_hash",
+    "create_transport_packet",
+    "ensure_tenant_context",
+    "last_hop_hash",
+    "make_dispatch_hop",
+    "make_execution_hop",
+    "make_ingress_hop",
+    "make_response_hop",
+    "sign_hop",
+    "utc_now",
+    "validate_hop_trace",
+    "verify_hop_signature",
+]

constellation_node_sdk/transport/codec.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any
+
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+def encode_transport_packet(packet: TransportPacket) -> dict[str, Any]:
+    """
+    Encode a TransportPacket into a JSON-safe dict.
+    """
+    return packet.model_dump_json_dict()
+
+
+def decode_transport_packet(payload: dict[str, Any]) -> TransportPacket:
+    """
+    Decode a JSON object into a canonical TransportPacket.
+    """
+    if not isinstance(payload, dict):
+        raise ValueError("transport payload must be a JSON object")
+    return TransportPacket.model_validate(payload)

constellation_node_sdk/transport/errors.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+
+class TransportError(Exception):
+    """Base exception for transport contract failures."""
+
+
+class TransportValidationError(TransportError):
+    """Raised when a transport packet violates structural or semantic rules."""
+
+
+class TransportIntegrityError(TransportValidationError):
+    """Raised when payload or transport hashes do not match."""
+
+
+class TransportAuthenticationError(TransportValidationError):
+    """Raised when transport authentication or signature state is invalid."""
+
+
+class TransportAuthorizationError(TransportValidationError):
+    """Raised when transport routing or delegation violates policy."""
+
+
+class TransportExpiredError(TransportValidationError):
+    """Raised when a packet has exceeded its expiry window."""
+
+
+class TransportNotYetValidError(TransportValidationError):
+    """Raised when a packet is not valid yet due to not_before constraints."""
+
+
+class TenantMutationError(TransportValidationError):
+    """Raised when a derived packet mutates immutable tenant context."""
+
+
+class SchemaVersionError(TransportValidationError):
+    """Raised when an unsupported schema version is encountered."""
+
+
+class PacketSizeError(TransportValidationError):
+    """Raised when a packet exceeds maximum allowed size."""