nullforge 0.1.0__py3-none-any.whl

nullforge/molds/__init__.py

@@ -0,0 +1,38 @@
+"""Configuration molds for NullForge."""
+
+from .base_mold import BaseMold
+from .containers import ContainersMold
+from .dns import DnsMold
+from .features import FeaturesMold
+from .haproxy import HaproxyMold
+from .monitoring import MonitoringMold
+from .netsec import FirewallRule, NetSecMold, SshMold
+from .profiles import ProfilesMold
+from .system import SystemMold
+from .telemt import TelemtMold
+from .tor import TorMold
+from .user import UserMold
+from .warp import WarpMold
+from .xray import XrayCoreMold
+from .zerotrust import ZeroTrustTunnelMold
+
+
+__all__ = [
+    "BaseMold",
+    "ContainersMold",
+    "DnsMold",
+    "FeaturesMold",
+    "FirewallRule",
+    "HaproxyMold",
+    "MonitoringMold",
+    "NetSecMold",
+    "ProfilesMold",
+    "SshMold",
+    "SystemMold",
+    "TelemtMold",
+    "TorMold",
+    "UserMold",
+    "WarpMold",
+    "XrayCoreMold",
+    "ZeroTrustTunnelMold",
+]

nullforge/molds/base_mold.py

@@ -0,0 +1,59 @@
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict
+
+
+REDACTED_VALUE = "***"
+
+
+class BaseMold(BaseModel):
+    """Base model class with JSON serialization support for pyinfra."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    _sensitive_fields: ClassVar[tuple[str, ...]] = ()
+    """Field names whose values are redacted by `to_json`."""
+
+    @property
+    def is_active(self) -> bool:
+        raise NotImplementedError(
+            f"{type(self).__name__}.is_active must be implemented as @property that "
+            "returns True when rune for this mold should be deployed."
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        """JSON-serializable representation for pyinfra's debug-inventory.
+
+        Uses JSON mode so that complex internal types (e.g. IPvAnyAddress, UUID, enums)
+        are serialized to simple primitives (str etc) while keeping rich types inside the model.
+        """
+
+        data = self.model_dump(mode="json")
+        return self._redact(self, data)
+
+    @classmethod
+    def _redact(cls, model: BaseModel, data: dict[str, Any]) -> dict[str, Any]:
+        """Redact model's sensitive fields and recurse into nested molds."""
+
+        sensitive = getattr(type(model), "_sensitive_fields", ())
+        for key in sensitive:
+            if data.get(key):
+                data[key] = REDACTED_VALUE
+
+        for name in type(model).model_fields:
+            value = getattr(model, name)
+            if name in data:
+                data[name] = cls._redact_value(value, data[name])
+        return data
+
+    @classmethod
+    def _redact_value(cls, value: Any, dumped: Any) -> Any:
+        """Mirror dumped value against live counterpart, redacting nested molds."""
+
+        if isinstance(value, BaseMold) and isinstance(dumped, dict):
+            return cls._redact(value, dumped)
+        if isinstance(value, (list, tuple)) and isinstance(dumped, list):
+            return [cls._redact_value(v, d) for v, d in zip(value, dumped)]
+        if isinstance(value, dict) and isinstance(dumped, dict):
+            return {k: cls._redact_value(value[k], d) for k, d in dumped.items() if k in value}
+        return dumped

nullforge/molds/containers.py

@@ -0,0 +1,26 @@
+"""Containers configuration mold."""
+
+from pydantic import Field
+
+from nullforge.models.containers import ContainersBackendType
+
+from .base_mold import BaseMold
+
+
+class ContainersMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to install containers backend",
+    )
+    backend_type: ContainersBackendType = Field(
+        default=ContainersBackendType.DOCKER,
+        description="Which containers backend to use",
+    )
+    skopeo: bool = Field(
+        default=True,
+        description="Whether to install skopeo",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install

nullforge/molds/defaults.py

@@ -0,0 +1,10 @@
+"""Base configuration presets."""
+
+from nullforge.molds import FeaturesMold, SystemMold
+
+
+BASE_FEATURES = FeaturesMold()
+"""Default features configuration."""
+
+BASE_SYSTEM = SystemMold()
+"""Default system configuration."""

nullforge/molds/dns.py

@@ -0,0 +1,70 @@
+"""DNS configuration mold."""
+
+from ipaddress import IPv4Address, IPv6Address
+from typing import TYPE_CHECKING
+
+from pydantic import Field, IPvAnyAddress, field_validator
+
+from nullforge.models.dns import DnsMode, DnsProvider
+
+from .base_mold import BaseMold
+
+
+class DnsMold(BaseMold):
+    """Full DNS configuration mold."""
+
+    mode: DnsMode = Field(
+        default=DnsMode.BLOCKY,
+        description="How DNS resolution should be performed",
+    )
+    upstream_provider: DnsProvider = Field(
+        default=DnsProvider.CLOUDFLARE,
+        description="Provider for upstream servers.",
+    )
+    ecs: bool = Field(
+        default=False,
+        description="Enable ECS (EDNS Client Subnet) for upstream provider.",
+    )
+    listen_address: IPvAnyAddress = Field(
+        default="169.254.0.53",
+        validate_default=True,
+        description=(
+            "IP address blocky binds to. Wildcards and loopback use existing interfaces; "
+            "non-global addresses create dedicated dummy interface."
+        ),
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.mode != DnsMode.NONE
+
+    if TYPE_CHECKING:
+        # NOTE: This stub widens `listen_address`
+        # Keep the list in sync with the fields above when they change.
+        def __init__(
+            self,
+            *,
+            mode: DnsMode = DnsMode.BLOCKY,
+            upstream_provider: DnsProvider = DnsProvider.CLOUDFLARE,
+            ecs: bool = False,
+            listen_address: IPvAnyAddress | str = "169.254.0.53",
+        ) -> None: ...
+
+    @field_validator("listen_address")
+    @classmethod
+    def _validate_listen_address(cls, v: IPv4Address | IPv6Address) -> IPv4Address | IPv6Address:
+        if v.is_unspecified or v.is_loopback:
+            return v
+
+        if not v.is_global:
+            return v
+
+        raise ValueError(f"listen_address {v!r} must be a wildcard, loopback, or non-global address.")
+
+    @property
+    def needs_custom_interface(self) -> bool:
+        """True when blocky should bind to dedicated dummy interface."""
+
+        if self.listen_address.is_unspecified or self.listen_address.is_loopback:
+            return False
+        return True

nullforge/molds/features.py

@@ -0,0 +1,75 @@
+"""Features controller model."""
+
+from collections.abc import Iterator
+
+from pydantic import Field
+
+from .base_mold import BaseMold
+from .containers import ContainersMold
+from .dns import DnsMold
+from .haproxy import HaproxyMold
+from .monitoring import MonitoringMold
+from .netsec import NetSecMold
+from .profiles import ProfilesMold
+from .telemt import TelemtMold
+from .tor import TorMold
+from .user import UserMold
+from .warp import WarpMold
+from .xray import XrayCoreMold
+from .zerotrust import ZeroTrustTunnelMold
+
+
+class FeaturesMold(BaseMold):
+    """Defines all supported molds and order of deployment."""
+
+    dns: DnsMold = Field(default_factory=DnsMold)
+    users: UserMold = Field(default_factory=UserMold)
+    netsec: NetSecMold = Field(default_factory=NetSecMold)
+    profiles: ProfilesMold = Field(default_factory=ProfilesMold)
+    warp: WarpMold = Field(default_factory=WarpMold)
+    zerotrust: ZeroTrustTunnelMold = Field(default_factory=ZeroTrustTunnelMold)
+    containers: ContainersMold = Field(default_factory=ContainersMold)
+    monitoring: MonitoringMold = Field(default_factory=MonitoringMold)
+    haproxy: HaproxyMold = Field(default_factory=HaproxyMold)
+    xray: XrayCoreMold = Field(default_factory=XrayCoreMold)
+    tor: TorMold = Field(default_factory=TorMold)
+    telemt: TelemtMold = Field(default_factory=TelemtMold)
+
+
+FEATURE_MOLD_MAPPING: dict[str, type[BaseMold]] = {}
+"""Derived after class definition. Adding a feature field automatically updates these."""
+
+
+def _build_mold_map() -> None:
+    global FEATURE_MOLD_MAPPING
+    mapping: dict[str, type[BaseMold]] = {}
+    for name, finfo in FeaturesMold.model_fields.items():
+        ann = finfo.annotation
+        if isinstance(ann, type) and issubclass(ann, BaseMold) and ann is not BaseMold:
+            mapping[name] = ann
+    FEATURE_MOLD_MAPPING = mapping
+
+
+_build_mold_map()
+
+ALLOWED_FEATURES_LAYERS: tuple[type[BaseMold], ...] = tuple(FEATURE_MOLD_MAPPING.values())
+"""Allowed molds for the FeaturesMold."""
+
+
+def iter_runes(features: FeaturesMold) -> Iterator[tuple[str, bool]]:
+    """Yield every dispatchable (rune name, active) pair, in a stable order.
+
+    Rune name defaults to attribute name under FeaturesMold (e.g. "warp" -> "warp").
+    Sub-mold classes may set `_feature_rune: ClassVar[str | None]`:
+      - str value overrides the rune stem
+      - None value opts the feature out of automatic dispatch
+    """
+
+    yielded: set[str] = set()
+
+    for attr, mold_cls in FEATURE_MOLD_MAPPING.items():
+        rune_name = getattr(mold_cls, "_feature_rune", attr)
+        if rune_name is None or rune_name in yielded:
+            continue
+        yielded.add(rune_name)
+        yield rune_name, getattr(features, attr).is_active

nullforge/molds/haproxy.py

@@ -0,0 +1,23 @@
+"""HAProxy configuration mold."""
+
+from pydantic import Field
+
+from .base_mold import BaseMold
+
+
+class HaproxyMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to install HAProxy proxy server",
+    )
+    version: str = Field(
+        default="3.2",
+        description=(
+            "HAProxy version to install from `haproxy.debian.net` (Debian) or `vbernat PPA` (Ubuntu). "
+            "Ignored on RHEL-based distros, which only offer version shipped by distro."
+        ),
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install

nullforge/molds/monitoring/__init__.py

@@ -0,0 +1,45 @@
+"""Monitoring configuration mold."""
+
+from typing import Annotated
+
+from pydantic import Field, model_validator
+
+from nullforge.models.monitoring import MonitoringBackendType
+
+from ..base_mold import BaseMold
+from .nezha import NezhaBackend
+
+
+MonitoringBackend = Annotated[NezhaBackend, Field(discriminator="type")]
+
+
+class MonitoringMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to deploy monitoring agent",
+    )
+    backend: MonitoringBackend = Field(
+        default_factory=NezhaBackend,
+        description="Monitoring backend and its configuration",
+    )
+
+    @model_validator(mode="after")
+    def _validate_install(self) -> "MonitoringMold":
+        if self.install:
+            self.backend.validate_enabled()
+        return self
+
+    @property
+    def backend_type(self) -> MonitoringBackendType:
+        return self.backend.type
+
+    @property
+    def is_active(self) -> bool:
+        return self.install
+
+
+__all__ = [
+    "MonitoringBackend",
+    "MonitoringMold",
+    "NezhaBackend",
+]

nullforge/molds/monitoring/nezha.py

@@ -0,0 +1,118 @@
+"""Nezha monitoring backend configuration mold."""
+
+from functools import cached_property
+from typing import TYPE_CHECKING, ClassVar, Literal
+from uuid import NAMESPACE_DNS, UUID, uuid5
+
+from pydantic import Field, field_validator
+
+from nullforge.models.monitoring import MonitoringBackendType, MonitoringLayout, monitoring_layout_factory
+
+from ..base_mold import BaseMold
+
+
+class NezhaBackend(BaseMold):
+    """Per-host configuration for the Nezha monitoring agent."""
+
+    _sensitive_fields: ClassVar[tuple[str, ...]] = ("client_secret", "api_token")
+
+    type: Literal[MonitoringBackendType.NEZHA] = Field(
+        default=MonitoringBackendType.NEZHA,
+        description="Discriminator selecting Nezha backend",
+    )
+    server: str = Field(
+        default="",
+        description="Agent->dashboard data endpoint as host:port (NZ_SERVER)",
+    )
+    dashboard_url: str = Field(
+        default="",
+        description="Dashboard HTTP base URL used for API calls",
+    )
+    tls: bool = Field(
+        default=True,
+        description="Use TLS for agent data channel (NZ_TLS)",
+    )
+    client_secret: str = Field(
+        default="",
+        description="Per-user connection secret (NZ_CLIENT_SECRET)",
+    )
+    disable_auto_update: bool = Field(
+        default=False,
+        description="Disable agent's self-update (NZ_DISABLE_AUTO_UPDATE)",
+    )
+    disable_command_execute: bool = Field(
+        default=True,
+        description="Disable dashboard-initiated command execution (NZ_DISABLE_COMMAND_EXECUTE)",
+    )
+    set_name_to_hostname: bool = Field(
+        default=True,
+        description="Rename auto-registered dashboard entry to host hostname",
+    )
+    api_token: str = Field(
+        default="",
+        description="Dashboard PAT (nzp_...) for API calls",
+    )
+    uuid_namespace: UUID | None = Field(
+        default=NAMESPACE_DNS,
+        description=("Namespace for deterministic agent UUIDv5 dashboard-unique generation"),
+    )
+
+    if TYPE_CHECKING:
+        # NOTE: This stub widens `uuid_namespace`
+        # Keep the list in sync with the fields above when they change.
+        def __init__(
+            self,
+            *,
+            type: Literal[MonitoringBackendType.NEZHA] = MonitoringBackendType.NEZHA,
+            server: str = "",
+            dashboard_url: str = "",
+            tls: bool = True,
+            client_secret: str = "",
+            disable_auto_update: bool = False,
+            disable_command_execute: bool = True,
+            set_name_to_hostname: bool = True,
+            api_token: str = "",
+            uuid_namespace: UUID | str | None = NAMESPACE_DNS,
+        ) -> None: ...
+
+    @field_validator("server", "dashboard_url", "client_secret", "api_token")
+    @classmethod
+    def _strip(cls, v: str) -> str:
+        return v.strip()
+
+    @field_validator("dashboard_url")
+    @classmethod
+    def _validate_dashboard_url(cls, v: str) -> str:
+        v = v.rstrip("/")
+        if v and not v.startswith("https://"):
+            raise ValueError("dashboard_url must start with https://")
+        return v
+
+    @field_validator("uuid_namespace", mode="before")
+    @classmethod
+    def _coerce_uuid_namespace(cls, v: object) -> UUID | None:
+        if v is None or isinstance(v, UUID):
+            return v
+        if isinstance(v, str):
+            v = v.strip()
+            if not v:
+                return None
+            try:
+                return UUID(v)
+            except ValueError:
+                return uuid5(UUID(int=0), v)
+        raise TypeError("uuid_namespace must be UUID, string, or None")
+
+    def validate_enabled(self) -> None:
+        """Assert config is complete enough to deploy."""
+
+        if not self.server:
+            raise ValueError("server is required when install is True")
+        if not self.client_secret:
+            raise ValueError("client_secret is required when install is True")
+        if self.set_name_to_hostname and (not self.dashboard_url or not self.api_token):
+            raise ValueError("dashboard_url and api_token are required when set_name_to_hostname is True")
+
+    @cached_property
+    def layout(self) -> MonitoringLayout:
+        return monitoring_layout_factory(self.type)