nullforge 0.1.0__py3-none-any.whl

nullforge/runes/warp.py

@@ -0,0 +1,273 @@
+"""Cloudflare WARP deployment module."""
+
+from pyinfra.api.operation import OperationMeta
+from pyinfra.context import host
+from pyinfra.facts.files import File
+from pyinfra.operations import files, server, systemd
+from pyinfra.operations.util import any_changed
+
+from nullforge.models.warp import WarpEngineType
+from nullforge.molds import FeaturesMold, WarpMold
+from nullforge.smithy.cloudflare import CLOUDFLARE_GROUP, CLOUDFLARE_USER
+from nullforge.smithy.install import install_release_binary
+from nullforge.smithy.network import has_ipv6
+from nullforge.smithy.packages import get_pm
+from nullforge.smithy.service import ensure_service_user
+from nullforge.smithy.versions import get_versions, is_pinned_version_installed, record_installed_version
+from nullforge.templates import get_template_path
+
+
+def deploy_warp() -> None:
+    """Deploy Cloudflare WARP configuration."""
+
+    features: FeaturesMold = host.data.features
+    warp_opts: WarpMold = features.warp
+
+    ensure_service_user(CLOUDFLARE_USER, CLOUDFLARE_GROUP, "/etc/cloudflare")
+
+    files.directory(
+        name="Ensure WARP engine configuration directory exists",
+        path=warp_opts.engine.config_dir,
+        user=CLOUDFLARE_USER,
+        group=CLOUDFLARE_GROUP,
+        mode="0755",
+        _sudo=True,
+    )
+
+    match warp_opts.engine_type:
+        case WarpEngineType.WIREGUARD:
+            _deploy_wireguard_warp(warp_opts)
+        case WarpEngineType.MASQUE:
+            _deploy_masque_warp(warp_opts)
+
+
+def _install_wgcf(opts: WarpMold) -> None:
+    """Install wgcf binary."""
+
+    if is_pinned_version_installed("wgcf", opts.engine.binary_path):
+        return
+
+    install_release_binary(
+        name="Install wgcf binary",
+        url=get_versions().wgcf_url(),
+        dest=opts.engine.binary_path,
+    )
+
+    record_installed_version("wgcf")
+
+
+def _deploy_wireguard_warp(opts: WarpMold) -> None:
+    """Deploy WARP using WireGuard."""
+
+    pm = get_pm()
+    pm.install(
+        name="Install WireGuard packages",
+        packages=["wireguard", "wireguard-tools"],
+        _sudo=True,
+    )
+
+    _install_wgcf(opts)
+
+    wgcf_account_path = opts.engine.account_path
+    wgcf_profile_path = opts.engine.profile_path
+    wgcf_bin = opts.engine.binary_path
+
+    register_op = None
+    if not host.get_fact(File, wgcf_account_path):
+        register_op = server.shell(
+            name="Register wgcf account",
+            commands=f"{wgcf_bin} register --accept-tos --config {wgcf_account_path}",
+            _retries=3,
+            _retry_delay=10,
+            _ignore_errors=True,
+        )
+
+    register_condition = register_op.did_succeed if register_op else (lambda: True)
+
+    generate_op = None
+    if not host.get_fact(File, wgcf_profile_path):
+        generate_op = server.shell(
+            name="Generate WireGuard profile",
+            commands=f"{wgcf_bin} generate --config {wgcf_account_path} --profile {wgcf_profile_path}",
+            _retries=3,
+            _retry_delay=10,
+            _ignore_errors=True,
+            _if=register_condition,
+        )
+
+        server.shell(
+            name="Post-process WireGuard profile",
+            commands=f"sed -i '/^DNS = /d' {wgcf_profile_path} "
+            rf"&& sed -i '/^\[Interface\]/a Table = off' {wgcf_profile_path}",
+            _if=generate_op.did_change,
+        )
+
+    def _wgcf_ok() -> bool:
+        """True iff every declared wgcf step really succeeded (or none were declared)."""
+
+        if register_op is not None and not register_op.did_succeed():
+            return False
+        if generate_op is not None and not generate_op.did_succeed():
+            return False
+        return True
+
+    profile_link = files.link(
+        name="Link WireGuard profile to /etc/wireguard/warp.conf",
+        path="/etc/wireguard/warp.conf",
+        target=wgcf_profile_path,
+        _sudo=True,
+        _if=_wgcf_ok,
+    )
+
+    restart_ops = [op for op in (register_op, generate_op, profile_link) if op]
+    systemd.service(
+        name="Restart WireGuard WARP on change",
+        service=opts.engine.systemd_service_name,
+        restarted=True,
+        _sudo=True,
+        _if=[_wgcf_ok, any_changed(*restart_ops)],
+    )
+
+    systemd.service(
+        name="Ensure WireGuard WARP is running and enabled",
+        service=opts.engine.systemd_service_name,
+        running=True,
+        enabled=True,
+        _sudo=True,
+        _if=_wgcf_ok,
+    )
+
+
+def _install_usque(opts: WarpMold) -> OperationMeta | None:
+    """Install usque binary."""
+
+    if is_pinned_version_installed("usque", opts.engine.binary_path):
+        return None
+
+    install_op = install_release_binary(
+        name="Extract and install usque binary",
+        url=get_versions().usque_zip(),
+        dest=opts.engine.binary_path,
+        binary_name="usque",
+    )
+
+    files.file(
+        name="Set usque binary as executable",
+        path=opts.engine.binary_path,
+        mode="0755",
+        user="root",
+        group=CLOUDFLARE_GROUP,
+        _sudo=True,
+    )
+
+    return install_op
+
+
+def _deploy_masque_warp(opts: WarpMold) -> None:
+    """Deploy WARP using Masque."""
+
+    binary_op = _install_usque(opts)
+
+    usque_config_path = opts.engine.config_path
+    usque_bin = opts.engine.binary_path
+    if not host.get_fact(File, usque_config_path):
+        server.shell(
+            name="Enroll device in Warp",
+            commands=f"{usque_bin} enroll -c {usque_config_path}",
+            _sudo=True,
+        )
+
+        register_op = server.shell(
+            name="Register device in Warp",
+            commands=f"{usque_bin} register -c {usque_config_path} --accept-tos",
+            _sudo=True,
+            _retries=3,
+            _retry_delay=10,
+            _ignore_errors=True,
+        )
+        config_condition = register_op.did_succeed
+    else:
+        config_condition = lambda: True  # noqa: E731  # config already exists, ops run unconditionally
+
+    files.file(
+        name="Ensure WARP config file ownership to cloudflare",
+        path=usque_config_path,
+        user=CLOUDFLARE_USER,
+        group=CLOUDFLARE_GROUP,
+        mode="0640",
+        _sudo=True,
+        _if=config_condition,
+    )
+
+    rt_tables_dir = "/etc/iproute2"
+    rt_tables_path = f"{rt_tables_dir}/rt_tables"
+    files.directory(
+        name="Create /etc/iproute2 directory",
+        path=rt_tables_dir,
+        user="root",
+        group="root",
+        mode="0755",
+        _sudo=True,
+        _if=config_condition,
+    )
+
+    files.file(
+        name=f"Set {rt_tables_path} group to cloudflare",
+        path=rt_tables_path,
+        group=CLOUDFLARE_GROUP,
+        mode="0664",
+        _sudo=True,
+        _if=config_condition,
+    )
+
+    policy_script = files.put(
+        name="Deploy WARP v6 policy script",
+        src=get_template_path("scripts/warp-v6-policy.sh"),
+        dest=opts.engine.policy_script,
+        user=CLOUDFLARE_USER,
+        group=CLOUDFLARE_GROUP,
+        mode="0755",
+        _sudo=True,
+        _if=config_condition,
+    )
+
+    service_template = files.template(
+        name="Deploy Masque WARP service configuration",
+        src=get_template_path("systemd/cloudflare-warp.service.j2"),
+        dest=f"/etc/systemd/system/{opts.engine.systemd_service_name}.service",
+        mode="0644",
+        WORKDIR=opts.engine.config_dir,
+        CONFIG_PATH=opts.engine.config_path,
+        MTU=opts.mtu,
+        INET_NAME=opts.iface,
+        USE_OUTBOUND_IPV6=has_ipv6(exclude_iface=opts.iface),
+        _sudo=True,
+        _if=config_condition,
+    )
+
+    systemd.daemon_reload(
+        name="Reload systemd daemon for Masque WARP",
+        _sudo=True,
+        _if=any_changed(policy_script, service_template),
+    )
+
+    restart_ops = [op for op in (binary_op, policy_script, service_template) if op]
+    systemd.service(
+        name="Restart Masque WARP on change",
+        service=opts.engine.systemd_service_name,
+        restarted=True,
+        _sudo=True,
+        _if=any_changed(*restart_ops),
+    )
+
+    systemd.service(
+        name="Ensure Masque WARP is running and enabled",
+        service=opts.engine.systemd_service_name,
+        running=True,
+        enabled=True,
+        _sudo=True,
+        _if=config_condition,
+    )
+
+
+deploy_warp()

nullforge/runes/xray.py

@@ -0,0 +1,81 @@
+"""Xray proxy deployment module."""
+
+from pyinfra.context import host
+from pyinfra.facts.files import File
+from pyinfra.operations import files, server, systemd
+
+from nullforge.molds import FeaturesMold, XrayCoreMold
+from nullforge.smithy.admin import ensure_acl_access
+from nullforge.smithy.http import CURL_ARGS
+from nullforge.smithy.versions import STATIC_URLS
+
+
+GEOIP_DAT_URL = "https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geoip.dat"
+GEOSITE_DAT_URL = "https://github.com/Loyalsoldier/v2ray-rules-dat/releases/latest/download/geosite.dat"
+
+GEO_DATS = {
+    "geoip.dat": GEOIP_DAT_URL,
+    "geosite.dat": GEOSITE_DAT_URL,
+}
+
+BASE_DIR = "/usr/local/share/xray"
+CONFIG_DIR = "/usr/local/etc/xray"
+
+
+def deploy_xray() -> None:
+    """Deploy Xray proxy configuration."""
+
+    features: FeaturesMold = host.data.features
+    xray_opts: XrayCoreMold = features.xray
+
+    _install_xray(xray_opts)
+    _download_geo_data()
+
+    systemd.service(
+        name="Ensure Xray is running and enabled",
+        service="xray",
+        running=True,
+        enabled=True,
+        _sudo=True,
+    )
+
+    if features.users.manage:
+        _setup_acls(features.users.name)
+
+
+def _install_xray(opts: XrayCoreMold) -> None:
+    """Install Xray using official installation script."""
+
+    if host.get_fact(File, "/usr/local/bin/xray"):
+        return
+
+    server.shell(
+        name="Install Xray proxy",
+        commands=f'bash -lc "$(curl -L {STATIC_URLS["xray_install"]})" @ install --beta',
+        _sudo=True,
+    )
+
+
+def _download_geo_data() -> None:
+    """Download GeoIP and GeoSite data files."""
+
+    for file, url in host.loop(GEO_DATS.items()):
+        files.download(
+            name=f"Download {file}",
+            src=url,
+            dest=f"{BASE_DIR}/{file}",
+            extra_curl_args=CURL_ARGS,
+            _sudo=True,
+            _retries=3,
+            _retry_delay=10,
+        )
+
+
+def _setup_acls(username: str) -> None:
+    """Set up ACLs on Xray directories for config management."""
+
+    ensure_acl_access(username, BASE_DIR)
+    ensure_acl_access(username, CONFIG_DIR, [f"{CONFIG_DIR}/config.json"])
+
+
+deploy_xray()

nullforge/runes/zerotrust.py

@@ -0,0 +1,91 @@
+"""Cloudflare Zero Trust Tunnel deployment module."""
+
+from pyinfra.context import host
+from pyinfra.operations import files, systemd
+from pyinfra.operations.util import any_changed
+
+from nullforge.molds import FeaturesMold, WarpMold, ZeroTrustTunnelMold
+from nullforge.smithy.cloudflare import CLOUDFLARE_GROUP, CLOUDFLARE_USER, ensure_cloudflared_binary
+from nullforge.smithy.service import ensure_service_user
+from nullforge.templates import BLOCK_TRIM_ENV, get_template_path
+
+
+def deploy_zerotrust_tunnel() -> None:
+    features: FeaturesMold = host.data.features
+    tunnel_opts: ZeroTrustTunnelMold = features.zerotrust
+
+    _deploy_tunnel(tunnel_opts, features.warp)
+
+
+def _deploy_tunnel(opts: ZeroTrustTunnelMold, warp_opts: WarpMold) -> None:
+    ensure_service_user(CLOUDFLARE_USER, CLOUDFLARE_GROUP, "/etc/cloudflare")
+    binary_op = ensure_cloudflared_binary()
+
+    config_dir = "/etc/cloudflare"
+    config_path = f"{config_dir}/tunnel.yml"
+    config_template = files.template(
+        name="Deploy Zero Trust Tunnel configuration",
+        src=get_template_path("cloudflared/tunnel.yml.j2"),
+        dest=config_path,
+        mode="0600",
+        user=CLOUDFLARE_USER,
+        group=CLOUDFLARE_GROUP,
+        jinja_env_kwargs=BLOCK_TRIM_ENV,
+        TOKEN=opts.token,
+        PROTOCOL=opts.protocol,
+        HA_CONNECTIONS=opts.ha_connections,
+        POST_QUANTUM=opts.post_quantum,
+        _sudo=True,
+    )
+
+    warp_route_script = None
+    if opts.route_through_warp:
+        warp_route_script = files.put(
+            name="Deploy Zero Trust tunnel WARP routing script",
+            src=get_template_path("scripts/zt-tunnel-warp.sh"),
+            dest=f"{config_dir}/zt-tunnel-warp.sh",
+            user=CLOUDFLARE_USER,
+            group=CLOUDFLARE_GROUP,
+            mode="0755",
+            _sudo=True,
+        )
+
+    service_template = files.template(
+        name="Deploy Zero Trust Tunnel systemd service",
+        src=get_template_path("systemd/cloudflare-tunnel.service.j2"),
+        dest="/etc/systemd/system/cloudflare-tunnel.service",
+        mode="0644",
+        jinja_env_kwargs=BLOCK_TRIM_ENV,
+        CONFIG_PATH=config_path,
+        WORKDIR=config_dir,
+        ROUTE_THROUGH_WARP=opts.route_through_warp,
+        WARP_IFACE=warp_opts.iface,
+        WARP_SERVICE=warp_opts.engine.systemd_service_name,
+        _sudo=True,
+    )
+
+    systemd.daemon_reload(
+        name="Reload systemd daemon for Zero Trust Tunnel",
+        _sudo=True,
+        _if=service_template.did_change,
+    )
+
+    restart_ops = [op for op in (binary_op, config_template, service_template, warp_route_script) if op]
+    systemd.service(
+        name="Restart Zero Trust Tunnel on change",
+        service="cloudflare-tunnel",
+        restarted=True,
+        _sudo=True,
+        _if=any_changed(*restart_ops),
+    )
+
+    systemd.service(
+        name="Ensure Zero Trust Tunnel is running and enabled",
+        service="cloudflare-tunnel",
+        running=True,
+        enabled=True,
+        _sudo=True,
+    )
+
+
+deploy_zerotrust_tunnel()

nullforge/smithy/__init__.py

@@ -0,0 +1 @@
+"""Helpers for NullForge."""

nullforge/smithy/admin.py

@@ -0,0 +1,40 @@
+"""Admin utilities for NullForge."""
+
+from pyinfra.context import host
+from pyinfra.facts.server import Command, User
+from pyinfra.operations import server
+
+
+def is_root() -> bool:
+    cache_key = "_nullforge_is_root"
+    if hasattr(host.data, cache_key):
+        return getattr(host.data, cache_key)
+
+    result = host.get_fact(User) == "root"
+
+    setattr(host.data, cache_key, result)
+    return result
+
+
+def _acl_entries(path: str) -> str:
+    return host.get_fact(Command, f"getfacl {path} 2>/dev/null || true", _sudo=True) or ""
+
+
+def ensure_acl_access(username: str, directory: str, rw_files: list[str] | None = None) -> None:
+    """Grant a user rwx ACL access to a directory, and optional rw to specific files."""
+
+    cmds: list[str] = []
+
+    if f"user:{username}:rwx" not in _acl_entries(directory):
+        cmds += [
+            f"setfacl -m u:{username}:rwx {directory}",
+            f"setfacl -d -m u:{username}:rwx {directory}",
+        ]
+
+    for f in rw_files or []:
+        entries = _acl_entries(f)
+        if entries and f"user:{username}:rw" not in entries:
+            cmds.append(f"setfacl -m u:{username}:rw {f}")
+
+    if cmds:
+        server.shell(name=f"Set ACLs on {directory}", commands=cmds, _sudo=True)

nullforge/smithy/arch.py

@@ -0,0 +1,36 @@
+"""Architecture utilities for NullForge."""
+
+import platform
+
+from pyinfra.context import host
+from pyinfra.facts.server import Arch
+
+
+def _normalize(a: str | None) -> str:
+    return {
+        "x86_64": "x86_64",
+        "amd64": "x86_64",
+        "aarch64": "arm64",
+        "arm64": "arm64",
+    }.get(a or "", a or "x86_64")
+
+
+def arch_id() -> str:
+    """Normalize arch id where vendors differ."""
+
+    cache_key = "_nullforge_arch_id"
+    try:
+        if hasattr(host.data, cache_key):
+            return getattr(host.data, cache_key)
+        result = _normalize(host.get_fact(Arch))
+        setattr(host.data, cache_key, result)
+        return result
+    except AttributeError:
+        return _normalize(platform.machine())
+
+
+def deb_arch() -> str:
+    return {
+        "x86_64": "amd64",
+        "arm64": "arm64",
+    }.get(arch_id(), "amd64")

nullforge/smithy/blocky.py

@@ -0,0 +1,37 @@
+"""Blocky DNS proxy setup module."""
+
+from pyinfra.api.operation import OperationMeta
+from pyinfra.context import host
+from pyinfra.operations import files
+
+from nullforge.smithy.install import install_release_binary
+from nullforge.smithy.versions import get_versions, is_pinned_version_installed
+
+
+BLOCKY_GROUP = "blocky"
+BLOCKY_USER = "blocky"
+BLOCKY_BINARY = "/usr/bin/blocky"
+
+
+def ensure_blocky_binary() -> OperationMeta | None:
+    if is_pinned_version_installed("blocky", BLOCKY_BINARY):
+        host.noop("blocky binary is already installed")
+        return None
+
+    install_op = install_release_binary(
+        name="Install blocky binary",
+        url=get_versions().blocky_tar(),
+        dest=BLOCKY_BINARY,
+        binary_name="blocky",
+    )
+
+    files.file(
+        name="Set blocky binary permissions",
+        path=BLOCKY_BINARY,
+        mode="0755",
+        user="root",
+        group=BLOCKY_GROUP,
+        _sudo=True,
+    )
+
+    return install_op

nullforge/smithy/cloudflare.py

@@ -0,0 +1,32 @@
+"""Cloudflare service management module."""
+
+from pyinfra.api.operation import OperationMeta
+from pyinfra.context import host
+from pyinfra.operations import files
+
+from nullforge.smithy.versions import get_versions, is_pinned_version_installed
+
+
+CLOUDFLARE_GROUP = "cloudflare"
+CLOUDFLARE_USER = "cloudflare"
+CLOUDFLARED_BINARY = "/usr/bin/cloudflared"
+
+
+def ensure_cloudflared_binary() -> OperationMeta | None:
+    if is_pinned_version_installed("cloudflared", CLOUDFLARED_BINARY):
+        host.noop("cloudflared binary is already installed")
+        return None
+
+    return files.download(
+        name="Install cloudflared binary",
+        src=get_versions().cloudflared_url(),
+        dest=CLOUDFLARED_BINARY,
+        mode="0755",
+        user=CLOUDFLARE_USER,
+        group=CLOUDFLARE_GROUP,
+        force=True,
+        extra_curl_args=get_versions().release_curl_args(),
+        _sudo=True,
+        _retries=3,
+        _retry_delay=10,
+    )