wyrmctl 0.4.0__py3-none-any.whl

wyrmctl/__init__.py

@@ -0,0 +1,3 @@
+"""wyrmctl: owner-scoped controller for Nginx Proxy Manager."""
+
+__version__ = "0.4.0"

wyrmctl/__main__.py

@@ -0,0 +1,5 @@
+"""python -m wyrmctl entry point."""
+
+from wyrmctl.cli import main
+
+raise SystemExit(main())

wyrmctl/adoption.py

@@ -0,0 +1,5 @@
+"""Adoption helpers."""
+
+from wyrmctl.planner import PlannerOptions, compute_plan
+
+__all__ = ["PlannerOptions", "compute_plan"]

wyrmctl/apply.py

@@ -0,0 +1,280 @@
+"""Apply owner-scoped plans to NPM."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from wyrmctl.client import NpmClient
+from wyrmctl.errors import ApiError, CertificateApiError, ConflictError, ValidationError
+from wyrmctl.issuance import CertificateIssuanceGuard
+from wyrmctl.metadata import merge_managed_meta
+from wyrmctl.models import (
+    DesiredAccessList,
+    DesiredCertificate,
+    DesiredGenericResource,
+    DesiredProxyHost,
+    ExistingResource,
+    ExistingState,
+    PlanAction,
+    ResourceKind,
+)
+from wyrmctl.planner import Plan, PlanOperation
+from wyrmctl.schema import Capabilities
+
+
+@dataclass(slots=True)
+class ApplyResult:
+    """Result of applying a plan."""
+
+    applied: bool
+    mutations: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"applied": self.applied, "mutations": list(self.mutations)}
+
+
+class ApplyEngine:
+    """Executes a validated plan in dependency order."""
+
+    def __init__(
+        self,
+        *,
+        client: NpmClient,
+        capabilities: Capabilities,
+        existing_state: ExistingState | None = None,
+        issuance_guard: CertificateIssuanceGuard | None = None,
+    ) -> None:
+        self.client = client
+        self.capabilities = capabilities
+        self.created_by_resource_id: dict[str, ExistingResource] = {}
+        self.issuance_guard = issuance_guard or CertificateIssuanceGuard()
+        if existing_state is not None:
+            for resource in existing_state.resources():
+                if resource.identity is not None:
+                    self.created_by_resource_id.setdefault(resource.identity.resource_id, resource)
+
+    def apply(self, plan: Plan) -> ApplyResult:
+        """Apply the plan. Conflicts prevent all mutations."""
+
+        if plan.conflicts:
+            raise ConflictError("refusing to apply plan with conflicts")
+        for operation in plan.operations:
+            if operation.desired is not None and operation.existing is not None:
+                self.created_by_resource_id.setdefault(operation.desired.identity.resource_id, operation.existing)
+        result = ApplyResult(applied=True)
+        for operation in _ordered_operations(plan.operations):
+            if operation.action == PlanAction.NOOP:
+                continue
+            mutation = self._apply_operation(operation)
+            result.mutations.append(mutation)
+        return result
+
+    def _apply_operation(self, operation: PlanOperation) -> dict[str, Any]:
+        if operation.action == PlanAction.CREATE:
+            return self._create(operation)
+        if operation.action == PlanAction.UPDATE:
+            return self._update(operation)
+        if operation.action == PlanAction.ADOPT:
+            return self._adopt(operation)
+        if operation.action == PlanAction.DELETE:
+            return self._delete(operation)
+        raise ValidationError(f"unsupported apply operation {operation.action}")
+
+    def _create(self, operation: PlanOperation) -> dict[str, Any]:
+        desired = _require_desired(operation)
+        payload = self._payload_for(desired)
+        issuance_key: str | None = None
+        try:
+            if isinstance(desired, DesiredCertificate):
+                issuance_key = self.issuance_guard.begin(desired)
+            created = self.client.create_resource(desired.kind, payload)
+        except CertificateApiError:
+            if issuance_key is not None:
+                self.issuance_guard.fail(issuance_key, error_code="certificate_api_error")
+            raise
+        except Exception:
+            if issuance_key is not None:
+                self.issuance_guard.fail(issuance_key, error_code="certificate_create_failed")
+            raise
+        if issuance_key is not None:
+            self.issuance_guard.succeed(issuance_key)
+        self.created_by_resource_id[desired.identity.resource_id] = created
+        return {
+            "action": "create",
+            "kind": desired.kind.value,
+            "resource_id": desired.identity.resource_id,
+            "id": created.id,
+        }
+
+    def _update(self, operation: PlanOperation) -> dict[str, Any]:
+        desired = _require_desired(operation)
+        existing = _require_existing(operation)
+        payload = self._merge_existing_with_desired(existing, desired)
+        cap = self.capabilities.for_kind(desired.kind)
+        issuance_key: str | None = None
+        try:
+            if isinstance(desired, DesiredCertificate):
+                issuance_key = self.issuance_guard.begin(desired)
+            updated = self.client.update_resource(desired.kind, existing.id, payload, method=cap.update_method or "put")
+        except CertificateApiError:
+            if issuance_key is not None:
+                self.issuance_guard.fail(issuance_key, error_code="certificate_api_error")
+            raise
+        except Exception:
+            if issuance_key is not None:
+                self.issuance_guard.fail(issuance_key, error_code="certificate_update_failed")
+            raise
+        if issuance_key is not None:
+            self.issuance_guard.succeed(issuance_key)
+        return {
+            "action": "update",
+            "kind": desired.kind.value,
+            "resource_id": desired.identity.resource_id,
+            "id": updated.id,
+        }
+
+    def _adopt(self, operation: PlanOperation) -> dict[str, Any]:
+        desired = _require_desired(operation)
+        existing = _require_existing(operation)
+        payload = _updateable_existing_payload(existing)
+        payload["meta"] = merge_managed_meta(payload.get("meta"), desired.meta)
+        cap = self.capabilities.for_kind(desired.kind)
+        updated = self.client.update_resource(desired.kind, existing.id, payload, method=cap.update_method or "put")
+        return {
+            "action": "adopt",
+            "kind": desired.kind.value,
+            "resource_id": desired.identity.resource_id,
+            "id": updated.id,
+        }
+
+    def _delete(self, operation: PlanOperation) -> dict[str, Any]:
+        existing = _require_existing(operation)
+        deleted = self.client.delete_resource(existing.kind, existing.id)
+        if not deleted:
+            raise ApiError(f"delete failed for {existing.kind.value} id={existing.id}")
+        resource_id = existing.identity.resource_id if existing.identity else None
+        return {"action": "delete", "kind": existing.kind.value, "resource_id": resource_id, "id": existing.id}
+
+    def _merge_existing_with_desired(
+        self,
+        existing: ExistingResource,
+        desired: DesiredProxyHost | DesiredCertificate | DesiredAccessList | DesiredGenericResource,
+    ) -> dict[str, Any]:
+        payload = self._payload_for(desired)
+        payload["meta"] = merge_managed_meta(existing.raw.get("meta"), desired.meta)
+        return payload
+
+    def _payload_for(
+        self, desired: DesiredProxyHost | DesiredCertificate | DesiredAccessList | DesiredGenericResource
+    ) -> dict[str, Any]:
+        if isinstance(desired, DesiredProxyHost):
+            certificate_id = self._resolve_reference(desired.certificate_ref, ResourceKind.CERTIFICATE)
+            access_list_id = self._resolve_reference(desired.access_list_ref, ResourceKind.ACCESS_LIST)
+            return desired.to_payload(certificate_id=certificate_id, access_list_id=access_list_id)
+        return desired.to_payload()
+
+    def _resolve_reference(self, ref: str | None, kind: ResourceKind) -> int | None:
+        if ref is None:
+            return None
+        created = self.created_by_resource_id.get(ref)
+        if created is not None:
+            if created.kind != kind:
+                raise ValidationError(f"reference {ref!r} resolved to {created.kind.value}, expected {kind.value}")
+            return created.id
+        raise ValidationError(f"unresolved {kind.value} reference: {ref}")
+
+
+def _ordered_operations(operations: tuple[PlanOperation, ...]) -> list[PlanOperation]:
+    creates_updates_adopts = [
+        op for op in operations if op.action in {PlanAction.CREATE, PlanAction.UPDATE, PlanAction.ADOPT}
+    ]
+    deletes = [op for op in operations if op.action == PlanAction.DELETE]
+    order = {
+        ResourceKind.CERTIFICATE: 0,
+        ResourceKind.ACCESS_LIST: 1,
+        ResourceKind.REDIRECTION_HOST: 2,
+        ResourceKind.DEAD_HOST: 2,
+        ResourceKind.STREAM: 2,
+        ResourceKind.USER: 2,
+        ResourceKind.SETTING: 2,
+        ResourceKind.PROXY_HOST: 3,
+    }
+    delete_order = {
+        ResourceKind.PROXY_HOST: 0,
+        ResourceKind.REDIRECTION_HOST: 1,
+        ResourceKind.DEAD_HOST: 1,
+        ResourceKind.STREAM: 1,
+        ResourceKind.USER: 1,
+        ResourceKind.SETTING: 1,
+        ResourceKind.ACCESS_LIST: 2,
+        ResourceKind.CERTIFICATE: 3,
+    }
+    return sorted(creates_updates_adopts, key=lambda op: order[op.kind]) + sorted(
+        deletes, key=lambda op: delete_order[op.kind]
+    )
+
+
+def _require_desired(
+    operation: PlanOperation,
+) -> DesiredProxyHost | DesiredCertificate | DesiredAccessList | DesiredGenericResource:
+    if operation.desired is None:
+        raise ValidationError(f"operation {operation.action} requires desired resource")
+    return operation.desired
+
+
+def _require_existing(operation: PlanOperation) -> ExistingResource:
+    if operation.existing is None:
+        raise ValidationError(f"operation {operation.action} requires existing resource")
+    return operation.existing
+
+
+def _updateable_existing_payload(existing: ExistingResource) -> dict[str, Any]:
+    fields = {
+        ResourceKind.PROXY_HOST: (
+            "domain_names",
+            "forward_scheme",
+            "forward_host",
+            "forward_port",
+            "certificate_id",
+            "ssl_forced",
+            "hsts_enabled",
+            "hsts_subdomains",
+            "http2_support",
+            "block_exploits",
+            "caching_enabled",
+            "allow_websocket_upgrade",
+            "access_list_id",
+            "advanced_config",
+            "enabled",
+            "locations",
+            "meta",
+        ),
+        ResourceKind.ACCESS_LIST: ("name", "satisfy_any", "pass_auth", "items", "clients", "meta"),
+        ResourceKind.CERTIFICATE: ("provider", "nice_name", "domain_names", "meta"),
+        ResourceKind.REDIRECTION_HOST: ("domain_names", "forward_domain_name", "meta"),
+        ResourceKind.DEAD_HOST: ("domain_names", "meta"),
+        ResourceKind.STREAM: ("incoming_port", "forward_host", "forward_port", "protocol", "meta"),
+        ResourceKind.USER: ("name", "email", "roles", "is_disabled", "meta"),
+        ResourceKind.SETTING: ("name", "value", "meta"),
+    }[existing.kind]
+    payload = {field: existing.raw[field] for field in fields if field in existing.raw}
+    if existing.kind == ResourceKind.PROXY_HOST:
+        defaults = {
+            "access_list_id": 0,
+            "certificate_id": 0,
+            "ssl_forced": 0,
+            "hsts_enabled": 0,
+            "hsts_subdomains": 0,
+            "http2_support": 0,
+            "block_exploits": 0,
+            "caching_enabled": 0,
+            "allow_websocket_upgrade": 0,
+            "advanced_config": "",
+            "enabled": 1,
+            "locations": [],
+        }
+        for field, default in defaults.items():
+            if payload.get(field) is None:
+                payload[field] = default
+    return payload

wyrmctl/artifacts/__init__.py

@@ -0,0 +1,24 @@
+"""Public immutable artifact API."""
+
+from wyrmctl.artifacts.codec import artifact_digest, read_artifact, write_artifact
+from wyrmctl.artifacts.execution import plan_from_artifact
+from wyrmctl.artifacts.models import ApplyReport, ArtifactSignature, LiveStateSnapshot, PlanArtifact
+from wyrmctl.artifacts.plan import build_plan_artifact, validate_plan_binding
+from wyrmctl.artifacts.redaction import redact_artifact
+from wyrmctl.artifacts.signing import sign_plan, verify_plan
+
+__all__ = [
+    "ApplyReport",
+    "ArtifactSignature",
+    "LiveStateSnapshot",
+    "PlanArtifact",
+    "artifact_digest",
+    "build_plan_artifact",
+    "plan_from_artifact",
+    "read_artifact",
+    "redact_artifact",
+    "sign_plan",
+    "validate_plan_binding",
+    "verify_plan",
+    "write_artifact",
+]

wyrmctl/artifacts/codec.py

@@ -0,0 +1,54 @@
+"""Versioned artifact encoding with atomic writes."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from wyrmctl.contracts import BUILTIN_CONTRACTS, check_document, semantic_digest
+from wyrmctl.errors import ArtifactError
+
+
+def read_artifact(path: str | Path, *, strict: bool = False) -> dict[str, Any]:
+    source = Path(path)
+    try:
+        text = source.read_text(encoding="utf-8")
+        value = json.loads(text) if source.suffix.lower() == ".json" else yaml.safe_load(text)
+    except (OSError, json.JSONDecodeError, yaml.YAMLError) as exc:
+        raise ArtifactError("ARTIFACT_READ_FAILED", f"failed to read artifact {source}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ArtifactError("INVALID_ARTIFACT", "artifact must contain an object")
+    check_document(value, BUILTIN_CONTRACTS, strict=strict)
+    return value
+
+
+def write_artifact(path: str | Path, value: dict[str, Any]) -> Path:
+    check_document(value, BUILTIN_CONTRACTS)
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    text = (
+        json.dumps(value, indent=2, sort_keys=True) + "\n"
+        if target.suffix.lower() == ".json"
+        else yaml.safe_dump(value, sort_keys=False)
+    )
+    handle, temp_name = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8", newline="\n") as stream:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temp_name, target)
+    except BaseException:
+        Path(temp_name).unlink(missing_ok=True)
+        raise
+    return target
+
+
+def artifact_digest(value: dict[str, Any]) -> str:
+    unsigned = {key: item for key, item in value.items() if key != "signature"}
+    return semantic_digest(unsigned)

wyrmctl/artifacts/execution.py

@@ -0,0 +1,105 @@
+"""Rehydrate an exact reviewed PlanArtifact for execution."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from wyrmctl.errors import ArtifactError
+from wyrmctl.models import (
+    DesiredAccessList,
+    DesiredCertificate,
+    DesiredGenericResource,
+    DesiredProxyHost,
+    ExistingResource,
+    PlanAction,
+    ResourceKind,
+)
+from wyrmctl.planner import Plan, PlanConflict, PlanOperation
+
+
+def plan_from_artifact(document: dict[str, Any]) -> Plan:
+    if document.get("kind") != "PlanArtifact" or document.get("schemaVersion") != 1:
+        raise ArtifactError("INVALID_PLAN_ARTIFACT", "apply requires a PlanArtifact schema 1 document")
+    spec = document.get("spec")
+    if not isinstance(spec, dict):
+        raise ArtifactError("INVALID_PLAN_ARTIFACT", "plan artifact spec must be an object")
+    operations = tuple(_operation(item, index) for index, item in enumerate(_items(spec, "operations")))
+    conflicts = tuple(_conflict(item, index) for index, item in enumerate(_items(spec, "conflicts")))
+    return Plan(operations, conflicts, sum(operation.existing is not None for operation in operations))
+
+
+def _operation(value: Any, index: int) -> PlanOperation:
+    item = _mapping(value, f"operations[{index}]")
+    try:
+        action = PlanAction(str(item["action"]))
+        kind = ResourceKind(str(item["kind"]))
+    except (KeyError, ValueError) as exc:
+        raise ArtifactError("INVALID_PLAN_OPERATION", f"invalid operation at index {index}") from exc
+    if action in {PlanAction.ADOPT, PlanAction.DELETE}:
+        raise ArtifactError(
+            "MIGRATION_REQUIRED",
+            f"{action.value} requires an NpmctlMigration artifact, not an ordinary PlanArtifact",
+        )
+    return PlanOperation(
+        action=action,
+        kind=kind,
+        desired=_desired(kind, item.get("desired"), index),
+        existing=_existing(kind, item.get("existing"), index),
+        reason=str(item.get("reason", "")),
+        diff=_mapping(item.get("diff", {}), f"operations[{index}].diff"),
+    )
+
+
+def _desired(kind: ResourceKind, value: Any, index: int) -> Any:
+    if value is None:
+        return None
+    item = _mapping(value, f"operations[{index}].desired")
+    path = f"artifact.operations[{index}].desired"
+    if kind == ResourceKind.PROXY_HOST:
+        return DesiredProxyHost.from_mapping(item, path=path)
+    if kind == ResourceKind.CERTIFICATE:
+        return DesiredCertificate.from_mapping(item, path=path)
+    if kind == ResourceKind.ACCESS_LIST:
+        return DesiredAccessList.from_mapping(item, path=path)
+    return DesiredGenericResource.from_mapping(kind, item, path=path)
+
+
+def _existing(kind: ResourceKind, value: Any, index: int) -> ExistingResource | None:
+    if value is None:
+        return None
+    item = _mapping(value, f"operations[{index}].existing")
+    raw = _mapping(item.get("raw"), f"operations[{index}].existing.raw")
+    factories = {
+        ResourceKind.PROXY_HOST: ExistingResource.from_proxy_host,
+        ResourceKind.CERTIFICATE: ExistingResource.from_certificate,
+        ResourceKind.ACCESS_LIST: ExistingResource.from_access_list,
+    }
+    factory = factories.get(kind)
+    return factory(raw) if factory else ExistingResource.from_generic(kind, raw)
+
+
+def _conflict(value: Any, index: int) -> PlanConflict:
+    item = _mapping(value, f"conflicts[{index}]")
+    raw_kind = item.get("kind")
+    return PlanConflict(
+        code=str(item.get("code", "artifact_conflict")),
+        message=str(item.get("message", "artifact contains a conflict")),
+        kind=ResourceKind(str(raw_kind)) if raw_kind else None,
+        owner=item.get("owner"),
+        resource_id=item.get("resource_id"),
+        existing_id=item.get("existing_id"),
+        domain=item.get("domain"),
+    )
+
+
+def _items(spec: dict[str, Any], key: str) -> list[Any]:
+    value = spec.get(key, [])
+    if not isinstance(value, list):
+        raise ArtifactError("INVALID_PLAN_ARTIFACT", f"plan artifact spec.{key} must be an array")
+    return value
+
+
+def _mapping(value: Any, path: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ArtifactError("INVALID_PLAN_ARTIFACT", f"{path} must be an object")
+    return dict(value)

wyrmctl/artifacts/models.py

@@ -0,0 +1,126 @@
+"""Immutable execution artifact models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from wyrmctl.contracts import semantic_digest
+from wyrmctl.profile import current_profile
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactSignature:
+    algorithm: str
+    key_id: str
+    value: str
+    signed_at: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"algorithm": self.algorithm, "keyId": self.key_id, "value": self.value, "signedAt": self.signed_at}
+
+
+@dataclass(frozen=True, slots=True)
+class PlanArtifact:
+    artifact_id: str
+    repository: str
+    environment: str
+    commit: str
+    desired_state_digest: str
+    live_state_fingerprint: str
+    operations: tuple[dict[str, Any], ...]
+    conflicts: tuple[dict[str, Any], ...] = ()
+    provider_capabilities: dict[str, int] = field(default_factory=dict)
+    api_profiles: dict[str, str] = field(default_factory=dict)
+    created_at: str = field(default_factory=utc_now)
+    expires_at: str | None = None
+    signature: ArtifactSignature | None = None
+
+    def unsigned_dict(self) -> dict[str, Any]:
+        return {
+            "apiVersion": current_profile().api_version,
+            "kind": "PlanArtifact",
+            "schemaVersion": 1,
+            "metadata": {
+                "id": self.artifact_id,
+                "repository": self.repository,
+                "environment": self.environment,
+                "createdAt": self.created_at,
+                "expiresAt": self.expires_at,
+            },
+            "spec": {
+                "source": {"commit": self.commit},
+                "inputs": {
+                    "desiredStateDigest": self.desired_state_digest,
+                    "liveStateFingerprint": self.live_state_fingerprint,
+                },
+                "providerCapabilities": self.provider_capabilities,
+                "apiProfiles": self.api_profiles,
+                "operations": list(self.operations),
+                "conflicts": list(self.conflicts),
+            },
+        }
+
+    @property
+    def digest(self) -> str:
+        return semantic_digest(self.unsigned_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = self.unsigned_dict()
+        if self.signature is not None:
+            payload["signature"] = self.signature.to_dict()
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class LiveStateSnapshot:
+    repository: str
+    environment: str
+    resources: tuple[dict[str, Any], ...]
+    observed_at: str = field(default_factory=utc_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "apiVersion": current_profile().api_version,
+            "kind": "LiveStateSnapshot",
+            "schemaVersion": 1,
+            "metadata": {
+                "repository": self.repository,
+                "environment": self.environment,
+                "observedAt": self.observed_at,
+            },
+            "spec": {"resources": list(self.resources)},
+        }
+
+    @property
+    def fingerprint(self) -> str:
+        return semantic_digest(self.to_dict()["spec"])
+
+
+@dataclass(frozen=True, slots=True)
+class ApplyReport:
+    plan_id: str
+    plan_digest: str
+    status: str
+    results: tuple[dict[str, Any], ...]
+    verification: dict[str, Any]
+    completed_at: str = field(default_factory=utc_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "apiVersion": current_profile().api_version,
+            "kind": "ApplyReport",
+            "schemaVersion": 1,
+            "metadata": {"planId": self.plan_id, "completedAt": self.completed_at},
+            "spec": {
+                "planArtifactDigest": self.plan_digest,
+                "status": self.status,
+                "results": list(self.results),
+                "verification": self.verification,
+            },
+        }