fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/lifecycle_infrastructure_agent.py

@@ -0,0 +1,174 @@
+"""Infrastructure agent envelope guard, destructive-change confirmation hold, and coordinator seam."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal, Protocol
+
+from fdai_deployment_cli.lifecycle_authorization import (
+    LifecycleAuthorizationReceipt,
+    LifecyclePhaseCompletionReceipt,
+    evaluate_phase_authorization,
+    exact_plan_digest_for,
+)
+from fdai_deployment_cli.lifecycle_plan import LifecyclePlan
+
+ResourceAction = Literal["create", "update", "delete", "replace"]
+InfraAgentOutcome = Literal["applied", "held-for-confirmation", "rejected"]
+
+_PREFIXED_SHA256 = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+_DESTRUCTIVE_ACTIONS = frozenset({"delete", "replace"})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PlannedResourceChange:
+    """One resource change rendered in an exact Terraform plan."""
+
+    address: str
+    resource_id: str
+    entity_id: str
+    region: str
+    actions: tuple[ResourceAction, ...]
+
+    def __post_init__(self) -> None:
+        if not self.address.strip() or not self.resource_id.strip():
+            raise ValueError("address and resource_id MUST NOT be empty")
+        if not self.entity_id.strip() or not self.region.strip():
+            raise ValueError("entity_id and region MUST NOT be empty")
+        if not self.actions:
+            raise ValueError("actions MUST NOT be empty")
+
+    @property
+    def is_destructive(self) -> bool:
+        action_set = set(self.actions)
+        return bool(action_set & _DESTRUCTIVE_ACTIONS)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DestructiveChangeConfirmation:
+    """Operator confirmation bound to the exact Plan digest and destructive resource addresses."""
+
+    exact_plan_digest: str
+    confirmed_addresses: frozenset[str]
+    operator: str
+    reason: str
+    confirmed_at: datetime
+
+    def __post_init__(self) -> None:
+        if _PREFIXED_SHA256.fullmatch(self.exact_plan_digest) is None:
+            raise ValueError("exact_plan_digest MUST be sha256:<64 hex>")
+        if not self.confirmed_addresses or any(
+            not addr.strip() for addr in self.confirmed_addresses
+        ):
+            raise ValueError("confirmed_addresses MUST NOT be empty")
+        if not self.operator.strip() or not self.reason.strip():
+            raise ValueError("operator and reason MUST NOT be empty")
+        if self.confirmed_at.tzinfo is None or self.confirmed_at.utcoffset() is None:
+            raise ValueError("confirmed_at MUST include timezone information")
+
+
+class ExactPlanCoordinator(Protocol):
+    """Existing exact-plan claim, apply, and verification-only recovery coordinator seam."""
+
+    def claim_apply_and_verify(
+        self,
+        *,
+        plan_id: str,
+        exact_plan_digest: str,
+        authorization_receipt_digest: str,
+        changes: tuple[PlannedResourceChange, ...],
+    ) -> bool: ...
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InfrastructurePhaseResult:
+    """Outcome of one infrastructure agent phase execution."""
+
+    outcome: InfraAgentOutcome
+    reason_code: str
+    held_addresses: tuple[str, ...] = ()
+    completion_receipt: LifecyclePhaseCompletionReceipt | None = None
+
+
+class InfrastructureAgent:
+    """Execute in-envelope infrastructure changes and hold deletions/replacements for confirmation."""
+
+    def __init__(self, coordinator: ExactPlanCoordinator) -> None:
+        self._coordinator = coordinator
+
+    def execute_phase(
+        self,
+        plan: LifecyclePlan,
+        *,
+        authorization_receipt: LifecycleAuthorizationReceipt | None,
+        planned_changes: Sequence[PlannedResourceChange],
+        trusted_now: datetime,
+        confirmation: DestructiveChangeConfirmation | None = None,
+    ) -> InfrastructurePhaseResult:
+        auth_decision = evaluate_phase_authorization(
+            plan,
+            phase="infrastructure",
+            authorization_receipt=authorization_receipt,
+            trusted_now=trusted_now,
+        )
+        if not auth_decision.allowed or authorization_receipt is None:
+            return InfrastructurePhaseResult(
+                outcome="rejected",
+                reason_code=auth_decision.reason_code,
+            )
+
+        changes = tuple(planned_changes)
+        for change in changes:
+            if (
+                change.entity_id not in plan.envelope.entity_ids
+                or change.region not in plan.envelope.regions
+            ):
+                return InfrastructurePhaseResult(
+                    outcome="rejected",
+                    reason_code="change_exceeds_envelope",
+                )
+
+        destructive_addresses = frozenset(
+            change.address for change in changes if change.is_destructive
+        )
+        expected_plan_digest = exact_plan_digest_for(plan)
+        if destructive_addresses:
+            if (
+                confirmation is None
+                or confirmation.exact_plan_digest != expected_plan_digest
+                or not destructive_addresses <= confirmation.confirmed_addresses
+            ):
+                return InfrastructurePhaseResult(
+                    outcome="held-for-confirmation",
+                    reason_code="destructive_change_confirmation_required",
+                    held_addresses=tuple(sorted(destructive_addresses)),
+                )
+
+        applied = self._coordinator.claim_apply_and_verify(
+            plan_id=plan.plan_id,
+            exact_plan_digest=expected_plan_digest,
+            authorization_receipt_digest=authorization_receipt.digest,
+            changes=changes,
+        )
+        if not applied:
+            return InfrastructurePhaseResult(
+                outcome="rejected",
+                reason_code="exact_plan_coordinator_failed",
+            )
+
+        receipt = LifecyclePhaseCompletionReceipt(
+            plan_id=plan.plan_id,
+            exact_plan_digest=expected_plan_digest,
+            fencing_generation=plan.fencing_generation,
+            phase="infrastructure",
+            authorization_receipt_digest=authorization_receipt.digest,
+            completed_at=trusted_now,
+        )
+        return InfrastructurePhaseResult(
+            outcome="applied",
+            reason_code="applied",
+            completion_receipt=receipt,
+        )

fdai_deployment_cli/lifecycle_installation_binding.py

@@ -0,0 +1,65 @@
+"""Private installation binding contract shared by the Hub infrastructure and workload agents."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from fdai_deployment_cli.private_output import write_private_output
+
+INSTALLATION_BINDING_FORMAT = "fdai.installation-binding.v1"
+_BINDING_KEY = re.compile(r"[a-z][a-z0-9_.-]{0,62}\Z", re.ASCII)
+_MAX_BINDING_VALUES = 128
+_MAX_BINDING_VALUE_LENGTH = 1024
+_CREDENTIAL_VALUE = re.compile(
+    r"(?i)([a-z][a-z0-9+.-]*://[^/\s]*@|\*{6}|accountkey=|sharedaccesskey=|-----BEGIN )"
+)
+
+
+def validate_installation_binding_values(
+    values: Mapping[str, object],
+    *,
+    allowed_keys: frozenset[str],
+) -> dict[str, str]:
+    """Validate exact reviewed Terraform outputs without exposing rejected values."""
+
+    if len(values) > _MAX_BINDING_VALUES:
+        raise ValueError("installation binding has too many values")
+    if set(values) - allowed_keys:
+        raise ValueError("installation binding names a key the bundle does not reference")
+    if allowed_keys - set(values):
+        raise ValueError("installation binding lacks a key the bundle references")
+    validated: dict[str, str] = {}
+    for key, value in values.items():
+        if not isinstance(key, str) or _BINDING_KEY.fullmatch(key) is None:
+            raise ValueError("installation binding key is invalid")
+        if (
+            not isinstance(value, str)
+            or not 1 <= len(value) <= _MAX_BINDING_VALUE_LENGTH
+            or any(ord(character) < 32 or ord(character) == 127 for character in value)
+            or _CREDENTIAL_VALUE.search(value)
+        ):
+            raise ValueError("installation binding value is invalid")
+        validated[key] = value
+    return validated
+
+
+def write_installation_binding(
+    path: Path,
+    values: Mapping[str, object],
+    *,
+    allowed_keys: frozenset[str],
+) -> None:
+    """Persist exact reviewed Terraform outputs as one private installation binding."""
+
+    validated = validate_installation_binding_values(values, allowed_keys=allowed_keys)
+    document = {
+        "format": INSTALLATION_BINDING_FORMAT,
+        "values": validated,
+    }
+    write_private_output(
+        path,
+        json.dumps(document, sort_keys=True, separators=(",", ":")),
+    )

fdai_deployment_cli/lifecycle_native.py

@@ -0,0 +1,247 @@
+"""Purpose-specific native workload creation evidence, not namespace ownership."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+from datetime import datetime, timedelta
+from typing import Annotated, Literal, Self
+from uuid import UUID
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    SerializerFunctionWrapHandler,
+    StringConstraints,
+    model_serializer,
+    model_validator,
+)
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest
+
+type Digest = Annotated[str, StringConstraints(pattern=r"^sha256:[0-9a-f]{64}$")]
+type PathId = Annotated[str, StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")]
+type DnsName = Annotated[str, StringConstraints(pattern=r"^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$")]
+type ProductId = Annotated[str, StringConstraints(pattern=r"^[a-z][a-z0-9-]{0,62}$")]
+
+
+class NativeScope(BaseModel):
+    """Exact private creation scope, independently supplied by the customer."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    installation_id: PathId
+    entity_id: Annotated[str, StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$")]
+    product: ProductId
+    namespace: DnsName
+    components: Annotated[tuple[DnsName, ...], Field(min_length=1, max_length=64)]
+    service_components: Annotated[tuple[DnsName, ...], Field(max_length=64)] | None = None
+    scheduled_components: Annotated[tuple[DnsName, ...], Field(max_length=64)] = ()
+    autoscaled_components: Annotated[tuple[DnsName, ...], Field(max_length=64)] = ()
+
+    @model_validator(mode="after")
+    def validate_components(self) -> Self:
+        if tuple(sorted(set(self.components))) != self.components:
+            raise ValueError("native components must be unique and sorted")
+        if self.anchor_name in self.components:
+            raise ValueError("a workload component conflicts with the native anchor")
+        if self.service_components is not None and (
+            tuple(sorted(set(self.service_components))) != self.service_components
+            or not set(self.service_components) <= set(self.components)
+        ):
+            raise ValueError("native Services must be a canonical subset of Deployments")
+        if (
+            tuple(sorted(set(self.scheduled_components))) != self.scheduled_components
+            or set(self.components) & set(self.scheduled_components)
+            or self.anchor_name in self.scheduled_components
+            or len(self.components) + len(self.scheduled_components) > 64
+        ):
+            raise ValueError("native scheduled components must be distinct and canonical")
+        if tuple(sorted(set(self.autoscaled_components))) != self.autoscaled_components or not set(
+            self.autoscaled_components
+        ) <= set(self.components):
+            raise ValueError("native autoscalers must be a canonical subset of Deployments")
+        return self
+
+    @model_serializer(mode="wrap")
+    def preserve_original_scope(self, handler: SerializerFunctionWrapHandler) -> dict[str, object]:
+        document: dict[str, object] = handler(self)
+        if not self.scheduled_components:
+            document.pop("scheduled_components", None)
+        if self.service_components is None:
+            document.pop("service_components", None)
+        if not self.autoscaled_components:
+            document.pop("autoscaled_components", None)
+        return document
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + canonical_digest(self.model_dump(mode="json"))
+
+    @property
+    def anchor_name(self) -> str:
+        identity = canonical_bytes(
+            {"installation_id": self.installation_id, "entity_id": self.entity_id}
+        )
+        return "lifecycle-scope-" + hashlib.sha256(identity).hexdigest()[:20]
+
+    @property
+    def resources(self) -> frozenset[tuple[str, str]]:
+        services = self.components if self.service_components is None else self.service_components
+        return (
+            frozenset(("Deployment", component) for component in self.components)
+            | frozenset(("Service", component) for component in services)
+            | frozenset(("CronJob", component) for component in self.scheduled_components)
+            | frozenset(
+                ("HorizontalPodAutoscaler", component) for component in self.autoscaled_components
+            )
+        )
+
+
+class NativeObjectIdentity(BaseModel):
+    """One existing Kubernetes object that a local approval permits the Agent to adopt."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    kind: Literal["Deployment", "Service", "CronJob", "HorizontalPodAutoscaler"]
+    name: DnsName
+    uid: Annotated[str, StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")]
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return self.kind, self.name
+
+
+class NativeApproval(BaseModel):
+    """Local human approval. A signed package or Hub request cannot supply this input."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    schema_version: Literal["fdai.lifecycle-native-approval.v1"]
+    scope: NativeScope
+    profile: Literal["full-authority-development"]
+    approved_by: Annotated[str, StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9@._ -]{0,127}$")]
+    approved_at: datetime
+    expires_at: datetime
+    existing_resources: tuple[NativeObjectIdentity, ...] = ()
+
+    @model_validator(mode="after")
+    def validate_interval(self) -> Self:
+        if self.approved_at.utcoffset() is None or self.expires_at.utcoffset() is None:
+            raise ValueError("native approval requires timezone-aware timestamps")
+        if not timedelta(0) < self.expires_at - self.approved_at <= timedelta(hours=4):
+            raise ValueError("native approval duration must be positive and at most four hours")
+        keys = tuple(item.key for item in self.existing_resources)
+        if tuple(sorted(set(keys))) != keys:
+            raise ValueError("existing native resources must be unique and sorted")
+        if not set(keys) <= self.scope.resources:
+            raise ValueError("existing native resources exceed the approved scope")
+        return self
+
+    @model_serializer(mode="wrap")
+    def preserve_creation_only_approval(
+        self, handler: SerializerFunctionWrapHandler
+    ) -> dict[str, object]:
+        document: dict[str, object] = handler(self)
+        if not self.existing_resources:
+            document.pop("existing_resources", None)
+        return document
+
+    def require_current(self, now: datetime) -> None:
+        if now.utcoffset() is None or not self.approved_at <= now < self.expires_at:
+            raise ValueError("native approval is not currently valid")
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + canonical_digest(self.model_dump(mode="json"))
+
+
+class NativeScopeClaim(BaseModel):
+    """Public digests of actual local creation; no namespace, UID or credential leaves."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    schema_version: Literal["fdai.lifecycle-native-scope.v1"]
+    installation_id: PathId
+    entity_id: PathId
+    product: ProductId
+    scope_digest: Digest
+    approval_digest: Digest
+    creation_receipt_digest: Digest
+
+    @property
+    def payload(self) -> bytes:
+        return canonical_bytes(self.model_dump(mode="json"))
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + canonical_digest(self.model_dump(mode="json"))
+
+
+class SignedNativeScope(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    claim: NativeScopeClaim
+    signature: Annotated[str, StringConstraints(min_length=88, max_length=88)]
+
+    @model_validator(mode="after")
+    def validate_signature(self) -> Self:
+        try:
+            decoded = base64.b64decode(self.signature, validate=True)
+        except (ValueError, binascii.Error) as error:
+            raise ValueError("native scope signature encoding is invalid") from error
+        if len(decoded) != 64 or base64.b64encode(decoded).decode("ascii") != self.signature:
+            raise ValueError("native scope signature must be canonical Ed25519 bytes")
+        return self
+
+    def verify(self, public_key: bytes) -> bool:
+        try:
+            Ed25519PublicKey.from_public_bytes(public_key).verify(
+                base64.b64decode(self.signature, validate=True), self.claim.payload
+            )
+        except (ValueError, InvalidSignature):
+            return False
+        return True
+
+
+def sign_native_scope(claim: NativeScopeClaim, key: Ed25519PrivateKey) -> SignedNativeScope:
+    return SignedNativeScope(
+        claim=claim, signature=base64.b64encode(key.sign(claim.payload)).decode("ascii")
+    )
+
+
+class NativeOwnershipAcceptance(BaseModel):
+    """Separate customer-operator acceptance, serialized with installation planning."""
+
+    model_config = ConfigDict(extra="forbid", strict=True, frozen=True)
+
+    request_id: UUID
+    expected_settings_digest: Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+    proof: SignedNativeScope
+    reason: Annotated[str, StringConstraints(min_length=1, max_length=512)]
+    confirmation: Annotated[str, StringConstraints(max_length=512)]
+
+    @model_validator(mode="after")
+    def validate_reason(self) -> Self:
+        if not self.reason.strip() or any(ord(character) < 32 for character in self.reason):
+            raise ValueError("native acceptance requires a nonblank single-line reason")
+        return self
+
+    @property
+    def digest(self) -> str:
+        return canonical_digest(self.model_dump(mode="json"))
+
+    @property
+    def required_confirmation(self) -> str:
+        claim = self.proof.claim
+        return (
+            f"accept native scope {claim.installation_id} {claim.entity_id} "
+            f"{claim.digest} {self.expected_settings_digest}"
+        )