nullforge 0.1.0__py3-none-any.whl

nullforge/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"  # x-release-please-version

nullforge/foundry/__init__.py

@@ -0,0 +1,7 @@
+"""Foundry deploy entry points for Pyinfra."""
+
+from pathlib import Path
+from typing import Final
+
+
+FOUNDRY_DIR: Final[Path] = Path(__file__).parent

nullforge/foundry/full_cast.py

@@ -0,0 +1,22 @@
+from pyinfra import local
+from pyinfra.context import host
+
+from nullforge.molds.features import iter_runes
+from nullforge.molds.utils import ensure_features, ensure_system
+from nullforge.runes import rune_path
+
+
+def cast_full() -> None:
+    host.data.features = ensure_features(getattr(host.data, "features", None))
+    host.data.system = ensure_system(getattr(host.data, "system", None))
+
+    local.include(str(rune_path("prepare")))
+
+    local.include(str(rune_path("base")))
+
+    for name, active in host.loop(iter_runes(host.data.features)):
+        if active:
+            local.include(str(rune_path(name)))
+
+
+cast_full()

nullforge/inventories/example.py

@@ -0,0 +1,87 @@
+from nullforge.models.dns import DnsMode
+from nullforge.models.users import Shell
+from nullforge.molds import DnsMold, MonitoringMold, TelemtMold, UserMold, WarpMold
+from nullforge.molds.defaults import BASE_FEATURES, BASE_SYSTEM
+from nullforge.molds.monitoring import NezhaBackend
+from nullforge.molds.utils import merge_features, merge_system
+
+
+users = UserMold(
+    manage=True,
+    name="example",
+    shell=Shell.ZSH,
+)
+"""User configuration preset
+with user management enabled and the user "example".
+with shell set to ZSH (default behavior).
+"""
+
+warp = WarpMold(
+    install=True,
+    iface="warp-example",
+)
+"""WARP configuration preset
+setup Cloudflare WARP
+with default MASQUE engine and interface "warp-example".
+"""
+
+dns = DnsMold(
+    mode=DnsMode.BLOCKY,
+)
+"""DNS configuration preset
+with DNS over HTTPS Blocky mode.
+"""
+
+monitoring = MonitoringMold(
+    install=True,
+    backend=NezhaBackend(
+        server="agent.status.example.com:443",
+        client_secret="REPLACE_WITH_NZ_CLIENT_SECRET",  # noqa: S106 - example placeholder
+        dashboard_url="https://dash.example.com",
+        api_token="REPLACE_WITH_DASHBOARD_PAT",  # noqa: S106 - example placeholder
+    ),
+)
+"""Monitoring configuration preset
+installing Nezha agent and renaming dashboard entry to host hostname.
+The dashboard_url/api_token are used on control node for rename API call.
+"""
+
+telemt = TelemtMold(
+    install=True,
+    tls_domain="example.com",
+    users={
+        "example": "bf777cca8384a074a671460d51e4e31f",
+    },
+    route_via_warp=True,
+    synfix=True,
+)
+"""Telemt MTProto proxy preset with Fake-TLS masking.
+Telegram-bound egress is routed through WARP (enabled above) via per-uid policy routing,
+and the MEKO SYN rate-limiting fix is applied.
+"""
+
+overrides = (
+    users,
+    warp,
+    dns,
+    monitoring,
+    telemt,
+)
+"""Wrappers for the features to be merged with the base features."""
+
+hosts = [
+    (
+        "203.0.113.10",
+        {
+            "system": merge_system(BASE_SYSTEM, {"hostname": "example-node1.local"}),
+            "features": merge_features(BASE_FEATURES, *overrides),
+        },
+    ),
+    (
+        "203.0.113.20",
+        {
+            "system": merge_system(BASE_SYSTEM, {"hostname": "example-node2.local"}),
+            "features": merge_features(BASE_FEATURES, *overrides),
+        },
+    ),
+]

nullforge/models/__init__.py

@@ -0,0 +1 @@
+"""Internal domain types for NullForge - pure value types."""

nullforge/models/containers.py

@@ -0,0 +1,60 @@
+"""Containers configuration models."""
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ContainersBackendType(StrEnum):
+    DOCKER = "docker"
+    PODMAN = "podman"
+    CRIO = "crio"
+
+
+class ContainersRuntimeType(StrEnum):
+    DEFAULT = "default"
+    CRUN = "crun"
+    GVISOR = "gvisor"
+
+
+class _ContainersBackendBase(BaseModel):
+    """Base for a containers backend."""
+
+    type: ContainersBackendType = Field(description="The type of containers backend")
+    runtime: ContainersRuntimeType = Field(description="The type of containers runtime")
+
+
+class DockerContainersBackend(_ContainersBackendBase):
+    type: Literal[ContainersBackendType.DOCKER] = ContainersBackendType.DOCKER
+    runtime: Literal[ContainersRuntimeType.GVISOR] = ContainersRuntimeType.GVISOR
+
+
+class PodmanContainersBackend(_ContainersBackendBase):
+    type: Literal[ContainersBackendType.PODMAN] = ContainersBackendType.PODMAN
+    runtime: Literal[ContainersRuntimeType.CRUN] = ContainersRuntimeType.CRUN
+
+
+class CrioContainersBackend(_ContainersBackendBase):
+    type: Literal[ContainersBackendType.CRIO] = ContainersBackendType.CRIO
+    runtime: Literal[ContainersRuntimeType.DEFAULT] = ContainersRuntimeType.DEFAULT
+
+
+ContainersBackend = Annotated[
+    DockerContainersBackend | PodmanContainersBackend | CrioContainersBackend,
+    Field(discriminator="type"),
+]
+
+
+def containers_backend_factory(type: ContainersBackendType) -> ContainersBackend:
+    """Factory function for containers backends."""
+
+    match type:
+        case ContainersBackendType.DOCKER:
+            return DockerContainersBackend()
+        case ContainersBackendType.PODMAN:
+            return PodmanContainersBackend()
+        case ContainersBackendType.CRIO:
+            return CrioContainersBackend()
+        case _:
+            raise ValueError(f"Unknown ContainersBackendType: {type}")

nullforge/models/dns.py

@@ -0,0 +1,222 @@
+"""DNS configuration models."""
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, IPvAnyAddress, field_validator
+
+
+class DnsProtocol(StrEnum):
+    DOU = "dou"
+    DOT = "dot"
+    DOH = "doh"
+
+
+class DnsMode(StrEnum):
+    DOU = "dou"
+    DOT_RESOLVED = "dot_resolved"
+    BLOCKY = "blocky"
+    NONE = "none"
+
+
+class DnsProvider(StrEnum):
+    CLOUDFLARE = "cloudflare"
+    GOOGLE = "google"
+    QUAD9 = "quad9"
+
+
+class _DnsServerBase(BaseModel):
+    """Base for a DNS server."""
+
+    protocol: DnsProtocol
+
+
+class DnsServerDoU(_DnsServerBase):
+    protocol: Literal[DnsProtocol.DOU] = DnsProtocol.DOU
+    host: IPvAnyAddress | str = Field(description="Resolver hostname or IP")
+    port: int = Field(default=53, ge=1, le=65535, description="UDP port")
+
+
+class DnsServerDoH(_DnsServerBase):
+    protocol: Literal[DnsProtocol.DOH] = DnsProtocol.DOH
+    url: str = Field(description="HTTPS endpoint for DNS over HTTPS (RFC 8484).")
+
+    @field_validator("url")
+    @classmethod
+    def _require_https(cls, v: str) -> str:
+        """Enforce HTTPS."""
+
+        if not v.startswith("https://"):
+            raise ValueError("DoH endpoint must use HTTPS")
+        return v
+
+
+class DnsServerDoT(_DnsServerBase):
+    protocol: Literal[DnsProtocol.DOT] = DnsProtocol.DOT
+    host: IPvAnyAddress | str = Field(description="Resolver hostname or IP")
+    port: int = Field(default=853, ge=1, le=65535, description="TLS port")
+    sni: str | None = Field(default=None, description="Optional SNI/hostname for TLS verification")
+
+
+DnsServer = Annotated[
+    DnsServerDoH | DnsServerDoT | DnsServerDoU,
+    Field(discriminator="protocol"),
+]
+
+
+class DnsProviders:
+    """DNS providers."""
+
+    @staticmethod
+    def _cloudflare_doh(ipv6: bool) -> list[DnsServer]:
+        ups: list[DnsServer] = [
+            DnsServerDoH(url="https://1.1.1.1/dns-query"),
+            DnsServerDoH(url="https://1.0.0.1/dns-query"),
+        ]
+        if ipv6:
+            ups.extend(
+                [
+                    DnsServerDoH(url="https://[2606:4700:4700::1111]/dns-query"),
+                    DnsServerDoH(url="https://[2606:4700:4700::1001]/dns-query"),
+                ]
+            )
+        return ups
+
+    @staticmethod
+    def _cloudflare_dot(ipv6: bool) -> list[DnsServer]:
+        ups: list[DnsServer] = [
+            DnsServerDoT(host="1.1.1.1", sni="cloudflare-dns.com"),
+            DnsServerDoT(host="1.0.0.1", sni="cloudflare-dns.com"),
+        ]
+        if ipv6:
+            ups.extend(
+                [
+                    DnsServerDoT(host="2606:4700:4700::1111", sni="cloudflare-dns.com"),
+                    DnsServerDoT(host="2606:4700:4700::1001", sni="cloudflare-dns.com"),
+                ]
+            )
+        return ups
+
+    @staticmethod
+    def _google_doh(ipv6: bool) -> list[DnsServer]:
+        ups: list[DnsServer] = [
+            DnsServerDoH(url="https://8.8.8.8/dns-query"),
+            DnsServerDoH(url="https://8.8.4.4/dns-query"),
+        ]
+        if ipv6:
+            ups.extend(
+                [
+                    DnsServerDoH(url="https://[2001:4860:4860::8888]/dns-query"),
+                    DnsServerDoH(url="https://[2001:4860:4860::8844]/dns-query"),
+                ]
+            )
+        return ups
+
+    @staticmethod
+    def _google_dot(ipv6: bool) -> list[DnsServer]:
+        ups: list[DnsServer] = [
+            DnsServerDoT(host="8.8.8.8", sni="dns.google"),
+            DnsServerDoT(host="8.8.4.4", sni="dns.google"),
+        ]
+        if ipv6:
+            ups.extend(
+                [
+                    DnsServerDoT(host="2001:4860:4860::8888", sni="dns.google"),
+                    DnsServerDoT(host="2001:4860:4860::8844", sni="dns.google"),
+                ]
+            )
+        return ups
+
+    @staticmethod
+    def _quad9_doh(ipv6: bool, ecs: bool) -> list[DnsServer]:
+        if ecs:
+            primary_ipv4 = "https://9.9.9.12/dns-query"
+            secondary_ipv4 = "https://149.112.112.12/dns-query"
+            primary_ipv6 = "https://[2620:fe::12]/dns-query"
+            secondary_ipv6 = "https://[2620:fe::fe:12]/dns-query"
+        else:
+            primary_ipv4 = "https://9.9.9.10/dns-query"
+            secondary_ipv4 = "https://149.112.112.10/dns-query"
+            primary_ipv6 = "https://[2620:fe::10]/dns-query"
+            secondary_ipv6 = "https://[2620:fe::fe:10]/dns-query"
+
+        ups: list[DnsServer] = [
+            DnsServerDoH(url=primary_ipv4),
+            DnsServerDoH(url=secondary_ipv4),
+        ]
+        if ipv6:
+            ups.extend(
+                [
+                    DnsServerDoH(url=primary_ipv6),
+                    DnsServerDoH(url=secondary_ipv6),
+                ]
+            )
+        return ups
+
+    @staticmethod
+    def _quad9_dot(ipv6: bool, ecs: bool) -> list[DnsServer]:
+        if ecs:
+            sni = "dns11.quad9.net"
+            primary_ipv4 = "9.9.9.12"
+            secondary_ipv4 = "149.112.112.12"
+            primary_ipv6 = "2620:fe::12"
+            secondary_ipv6 = "2620:fe::fe:12"
+        else:
+            sni = "dns10.quad9.net"
+            primary_ipv4 = "9.9.9.10"
+            secondary_ipv4 = "149.112.112.10"
+            primary_ipv6 = "2620:fe::10"
+            secondary_ipv6 = "2620:fe::fe:10"
+
+        ups: list[DnsServer] = [
+            DnsServerDoT(host=primary_ipv4, sni=sni),
+            DnsServerDoT(host=secondary_ipv4, sni=sni),
+        ]
+        if ipv6:
+            ups.extend(
+                [
+                    DnsServerDoT(host=primary_ipv6, sni=sni),
+                    DnsServerDoT(host=secondary_ipv6, sni=sni),
+                ]
+            )
+        return ups
+
+    @staticmethod
+    def get_upstreams(
+        provider: DnsProvider,
+        protocol: DnsProtocol,
+        ipv6: bool,
+        ecs: bool = False,
+    ) -> list[DnsServer]:
+        """Get upstream DNS servers for a provider and protocol."""
+
+        if ecs and provider != DnsProvider.QUAD9:
+            raise ValueError(f"ECS is supported only with the Quad9 provider, not {provider}")
+
+        match provider:
+            case DnsProvider.CLOUDFLARE:
+                if protocol == DnsProtocol.DOH:
+                    return DnsProviders._cloudflare_doh(ipv6)
+                elif protocol == DnsProtocol.DOT:
+                    return DnsProviders._cloudflare_dot(ipv6)
+                else:
+                    raise ValueError(f"Unsupported protocol {protocol} for Cloudflare")
+            case DnsProvider.GOOGLE:
+                if protocol == DnsProtocol.DOH:
+                    return DnsProviders._google_doh(ipv6)
+                elif protocol == DnsProtocol.DOT:
+                    return DnsProviders._google_dot(ipv6)
+                else:
+                    raise ValueError(f"Unsupported protocol {protocol} for Google")
+            case DnsProvider.QUAD9:
+                if protocol == DnsProtocol.DOH:
+                    return DnsProviders._quad9_doh(ipv6, ecs)
+                elif protocol == DnsProtocol.DOT:
+                    return DnsProviders._quad9_dot(ipv6, ecs)
+                else:
+                    raise ValueError(f"Unsupported protocol {protocol} for Quad9")
+            case _:
+                raise ValueError(f"Unknown provider: {provider}")
+
+
+dns_providers = DnsProviders()

nullforge/models/monitoring/__init__.py

@@ -0,0 +1,29 @@
+"""Monitoring configuration models."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from .base import MonitoringBackendType, _MonitoringLayoutBase
+from .nezha import NezhaLayout
+
+
+MonitoringLayout = Annotated[NezhaLayout, Field(discriminator="type")]
+"""Union-of-one for now. When second monitoring backend is added, extend union."""
+
+
+def monitoring_layout_factory(type: MonitoringBackendType) -> MonitoringLayout:
+    match type:
+        case MonitoringBackendType.NEZHA:
+            return NezhaLayout()
+        case _:
+            raise ValueError(f"Unknown MonitoringBackendType: {type}")
+
+
+__all__ = [
+    "MonitoringBackendType",
+    "MonitoringLayout",
+    "NezhaLayout",
+    "_MonitoringLayoutBase",
+    "monitoring_layout_factory",
+]

nullforge/models/monitoring/base.py

@@ -0,0 +1,19 @@
+"""Shared monitoring backend value types."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class MonitoringBackendType(StrEnum):
+    NEZHA = "nezha"
+
+
+class _MonitoringLayoutBase(BaseModel):
+    """Static on-disk/service layout for monitoring agent backend."""
+
+    type: MonitoringBackendType = Field(description="The monitoring backend type")
+    base_dir: str | None = Field(..., description="The base/installation directory")
+    binary_path: str | None = Field(..., description="The path to the binary")
+    config_path: str | None = Field(..., description="The path to the configuration file")
+    systemd_service_name: str | None = Field(..., description="The systemd service name")

nullforge/models/monitoring/nezha.py

@@ -0,0 +1,13 @@
+"""Nezha monitoring backend layout."""
+
+from typing import Literal
+
+from .base import MonitoringBackendType, _MonitoringLayoutBase
+
+
+class NezhaLayout(_MonitoringLayoutBase):
+    type: Literal[MonitoringBackendType.NEZHA] = MonitoringBackendType.NEZHA
+    base_dir: Literal["/opt/nezha/agent"] = "/opt/nezha/agent"
+    binary_path: Literal["/opt/nezha/agent/nezha-agent"] = "/opt/nezha/agent/nezha-agent"
+    config_path: Literal["/opt/nezha/agent/config.yml"] = "/opt/nezha/agent/config.yml"
+    systemd_service_name: Literal["nezha-agent"] = "nezha-agent"

nullforge/models/netsec.py

@@ -0,0 +1,43 @@
+"""Network security domain types."""
+
+from enum import StrEnum
+
+
+class SshHostKeyType(StrEnum):
+    """Host key type sshd offers."""
+
+    ED25519 = "ed25519"
+    ECDSA = "ecdsa"
+    RSA = "rsa"
+
+
+PQ_KEX_ALGORITHMS = (
+    "mlkem768x25519-sha256",
+    "sntrup761x25519-sha512@openssh.com",
+)
+"""Post-quantum hybrid key exchange algorithms, most preferred first."""
+
+CLASSICAL_KEX_ALGORITHMS = (
+    "curve25519-sha256",
+    "curve25519-sha256@libssh.org",
+    "diffie-hellman-group-exchange-sha256",
+    "diffie-hellman-group16-sha512",
+    "diffie-hellman-group18-sha512",
+)
+"""Strong classical key exchange in default-preference order, offered after the PQ hybrids."""
+
+WEAK_KEX_PATTERNS = "ecdh-sha2-*,diffie-hellman-group14-*,diffie-hellman-group-exchange-sha1"
+"""Key exchanges removed from default set."""
+
+WEAK_MAC_PATTERNS = "hmac-sha1*,umac-64*,hmac-sha2-256,hmac-sha2-512,umac-128@openssh.com"
+"""MACs removed from default set."""
+
+MIN_DH_MODULUS_SIZE = 3071
+"""Minimum size kept in /etc/ssh/moduli; the file's size column is bits-1, so 3071 keeps >=3072-bit groups."""
+
+HOST_KEY_ALGORITHMS: dict[SshHostKeyType, tuple[str, ...]] = {
+    SshHostKeyType.ED25519: ("ssh-ed25519",),
+    SshHostKeyType.ECDSA: ("ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521"),
+    SshHostKeyType.RSA: ("rsa-sha2-512", "rsa-sha2-256"),
+}
+"""Signature algorithms sshd may use per host key type."""

nullforge/models/profiles.py

@@ -0,0 +1,33 @@
+"""Profiles domain models."""
+
+from enum import StrEnum
+
+
+class NerdFont(StrEnum):
+    """Nerd Font family, valued as its base asset name in a `ryanoasis/nerd-fonts` release.
+
+    A curated subset of the ~70 published families; add a member to offer another one.
+    """
+
+    CASCADIA_CODE = "CascadiaCode"
+    COMMIT_MONO = "CommitMono"
+    DEJAVU_SANS_MONO = "DejaVuSansMono"
+    FIRA_CODE = "FiraCode"
+    FIRA_MONO = "FiraMono"
+    GEIST_MONO = "GeistMono"
+    HACK = "Hack"
+    IBM_PLEX_MONO = "IBMPlexMono"
+    INCONSOLATA = "Inconsolata"
+    INTEL_ONE_MONO = "IntelOneMono"
+    IOSEVKA = "Iosevka"
+    JETBRAINS_MONO = "JetBrainsMono"
+    MESLO = "Meslo"
+    MONASPACE = "Monaspace"
+    MONONOKI = "Mononoki"
+    ROBOTO_MONO = "RobotoMono"
+    SOURCE_CODE_PRO = "SourceCodePro"
+    SPACE_MONO = "SpaceMono"
+    SYMBOLS_ONLY = "NerdFontsSymbolsOnly"
+    UBUNTU_MONO = "UbuntuMono"
+    VICTOR_MONO = "VictorMono"
+    ZED_MONO = "ZedMono"

nullforge/models/system.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+
+
+class SwapType(StrEnum):
+    """Type of swap configuration."""
+
+    BASIC = "basic"
+    ZRAM = "zram"
+
+
+class SwapAlgo(StrEnum):
+    """Algorithm for ZRAM compression."""
+
+    ZSTD = "zstd"
+    LZO = "lzo"

nullforge/models/users.py

@@ -0,0 +1,9 @@
+"""User configuration models."""
+
+from enum import StrEnum
+
+
+class Shell(StrEnum):
+    BASH = "/bin/bash"
+    ZSH = "/bin/zsh"
+    ZSH_USER = "/usr/bin/zsh"

nullforge/models/warp.py

@@ -0,0 +1,65 @@
+"""WARP configuration models."""
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class WarpEngineType(StrEnum):
+    WIREGUARD = "wireguard"
+    MASQUE = "masque"
+
+
+class _WarpEngineBase(BaseModel):
+    """Base for a WARP engine."""
+
+    type: WarpEngineType = Field(description="The type of WARP engine")
+    binary_path: str = Field(description="The path to the WARP binary")
+    config_dir: str = Field(description="The path to the WARP configuration directory")
+    systemd_service_name: str = Field(description="The name of the systemd service")
+    policy_script: str = Field(default="", description="The path to the WARP policy script")
+
+    @property
+    def config_path(self) -> str:
+        return f"{self.config_dir}/config.json"
+
+    @property
+    def account_path(self) -> str:
+        return f"{self.config_dir}/wgcf-account.toml"
+
+    @property
+    def profile_path(self) -> str:
+        return f"{self.config_dir}/warp.conf"
+
+
+class MasqueWarpEngine(_WarpEngineBase):
+    type: Literal[WarpEngineType.MASQUE] = WarpEngineType.MASQUE
+    binary_path: Literal["/usr/local/bin/usque"] = "/usr/local/bin/usque"
+    config_dir: Literal["/etc/usque"] = "/etc/usque"
+    systemd_service_name: Literal["cloudflare-warp"] = "cloudflare-warp"
+    policy_script: Literal["/etc/usque/warp-v6-policy.sh"] = "/etc/usque/warp-v6-policy.sh"
+
+
+class WireguardWarpEngine(_WarpEngineBase):
+    type: Literal[WarpEngineType.WIREGUARD] = WarpEngineType.WIREGUARD
+    binary_path: Literal["/usr/local/bin/wgcf"] = "/usr/local/bin/wgcf"
+    config_dir: Literal["/etc/wgcf"] = "/etc/wgcf"
+    systemd_service_name: Literal["wg-quick@warp"] = "wg-quick@warp"
+    policy_script: Literal[""] = ""
+
+
+WarpEngine = Annotated[
+    MasqueWarpEngine | WireguardWarpEngine,
+    Field(discriminator="type"),
+]
+
+
+def warp_engine_factory(type: WarpEngineType) -> WarpEngine:
+    match type:
+        case WarpEngineType.MASQUE:
+            return MasqueWarpEngine()
+        case WarpEngineType.WIREGUARD:
+            return WireguardWarpEngine()
+        case _:
+            raise ValueError(f"Unknown WarpEngineType: {type}")

nullforge/models/zerotrust.py

@@ -0,0 +1,9 @@
+"""Zero Trust Tunnel configuration models."""
+
+from enum import StrEnum
+
+
+class ZeroTrustTunnelProtocol(StrEnum):
+    HTTP2 = "http2"
+    QUIC = "quic"
+    AUTO = "auto"