prototype copyparty reverse proxy config

AGENTS.md

@@ -99,3 +99,5 @@ The domain model (Host, Module, Skeleton, Auto-loader, Enable convention, overla
 - The current Steam desktop client is an XWayland application.
   Its CEF windows do not support Ozone and Steam composites them into an SDL surface with X11 extensions, so SDL Wayland selectors do not make the visible client native Wayland.
   Keep fractional scaling sharp with Hyprland's `xwayland.force_zero_scaling` and Steam's own `STEAM_FORCE_DESKTOPUI_SCALING` instead.
+- AdGuard's LAN wildcard rewrite for `*.alexion.dev` points names at the reverse-proxy guest, including non-HTTP ports.
+  Keep `git.alexion.dev:2022` working by proxying that TCP stream through the reverse-proxy guest to Gitea.

flake.nix

@@ -117,6 +117,92 @@
             ${lib.optionalString (!serviceIdentityTestsPass) "exit 1"}
             touch $out
           '';
+
+          reverse-proxy-basic-route =
+            let
+              testConfig =
+                (lib.nixosSystem {
+                  system = "x86_64-linux";
+                  specialArgs.my = self.lib;
+                  modules = [
+                    ./modules/reverse-proxy.nix
+                    {
+                      modules.reverse-proxy = {
+                        enable = true;
+                        routes."budget.alexion.dev" = {
+                          path = "/";
+                          backend = "http://10.23.20.42:5006";
+                        };
+                      };
+                    }
+                  ];
+                }).config;
+              vhost = testConfig.services.nginx.virtualHosts."budget.alexion.dev";
+            in
+            pkgs.runCommand "reverse-proxy-basic-route-check" { } ''
+              ${
+                lib.optionalString (
+                  !(vhost.forceSSL && vhost.enableACME && vhost.locations."/".proxyPass == "http://10.23.20.42:5006")
+                ) "exit 1"
+              }
+              touch $out
+            '';
+
+          reverse-proxy-actualbudget-guest-route =
+            let
+              testConfig =
+                (self.nixosConfigurations.pikachu.extendModules {
+                  modules = [
+                    {
+                      guests.actualbudget.reverseProxy = {
+                        enable = true;
+                        host = "budget.alexion.dev";
+                        backend = "http://10.23.20.42:5006";
+                      };
+                    }
+                  ];
+                }).config;
+              route = testConfig.modules.reverse-proxy.routes.actualbudget;
+            in
+            pkgs.runCommand "reverse-proxy-actualbudget-guest-route-check" { } ''
+              ${
+                lib.optionalString (
+                  !(route.host == "budget.alexion.dev" && route.backend == "http://10.23.20.42:5006")
+                ) "exit 1"
+              }
+              touch $out
+            '';
+
+          reverse-proxy-secondary-path-requires-root =
+            let
+              testConfig =
+                (lib.nixosSystem {
+                  system = "x86_64-linux";
+                  specialArgs.my = self.lib;
+                  modules = [
+                    ./modules/reverse-proxy.nix
+                    {
+                      modules.reverse-proxy = {
+                        enable = true;
+                        routes.raichu-files = {
+                          host = "files.alexion.dev";
+                          path = "/raichu";
+                          backend = "http://10.23.20.10:3923";
+                        };
+                      };
+                    }
+                  ];
+                }).config;
+              hasFailedRootAssertion = lib.any (
+                assertion:
+                assertion.assertion == false
+                && assertion.message == "modules.reverse-proxy.routes for files.alexion.dev must include a primary / route."
+              ) testConfig.assertions;
+            in
+            pkgs.runCommand "reverse-proxy-secondary-path-requires-root-check" { } ''
+              ${lib.optionalString (!hasFailedRootAssertion) "exit 1"}
+              touch $out
+            '';
         };
     };
 }

guests/copyparty.nix

@@ -43,6 +43,10 @@ in
           enable = true;
           inherit (cfg) accountName stateDir;
           passwordFile = "/run/secrets/${cfg.passwordSecret}";
+          reverseProxy = {
+            enable = cfg.reverseProxy.enable;
+            inherit (cfg.reverseProxy) trustedSources;
+          };
           volumes = lib.mapAttrs (_urlPath: volume: {
             inherit (volume) path access flags;
           }) cfg.volumes;
@@ -77,6 +81,12 @@ in
       description = "Host path bind-mounted as Copyparty's state directory.";
     };
 
+    reverseProxy.trustedSources = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [ ];
+      description = "IP ranges that may supply Copyparty's forwarded client IP header.";
+    };
+
     volumes = lib.mkOption {
       type = lib.types.attrsOf volumeType;
       default = { };

guests/reverse-proxy.nix

@@ -0,0 +1,61 @@
+{
+  config,
+  lib,
+  my,
+  ...
+}:
+let
+  giteaSshBackend = "10.23.20.45:2022";
+  legacyBackend = "http://10.23.20.32";
+  legacyHosts = [
+    "games.alexion.dev"
+    "git.alexion.dev"
+    "music.alexion.dev"
+    "photos.alexion.dev"
+    "plex.alexion.dev"
+    "servers.alexion.dev"
+    "todo.alexion.dev"
+    "wings.alexion.dev"
+  ];
+  legacyRoutes = lib.listToAttrs (
+    map (host: {
+      name = "legacy-${lib.replaceStrings [ "." ] [ "-" ] host}";
+      value = {
+        inherit host;
+        backend = legacyBackend;
+      };
+    }) legacyHosts
+  );
+in
+{
+  imports = [
+    (my.guest {
+      name = "reverse-proxy";
+      interior = {
+        modules.reverse-proxy = {
+          enable = true;
+          routes = config.modules.reverse-proxy.routes // legacyRoutes;
+        };
+
+        networking.firewall.allowedTCPPorts = [ 2022 ];
+
+        services.nginx.streamConfig = ''
+          server {
+            listen 2022;
+            proxy_pass ${giteaSshBackend};
+          }
+        '';
+      };
+    })
+  ];
+
+  config = lib.mkIf config.guests.reverse-proxy.enable {
+    guests.reverse-proxy = {
+      limits = {
+        memory = lib.mkDefault "1G";
+        cpu = lib.mkDefault "100%";
+        tasksMax = lib.mkDefault 256;
+      };
+    };
+  };
+}

hosts/pikachu/default.nix

@@ -79,6 +79,17 @@
     vlan = 20;
     mac = "BC:24:11:C1:CD:28";
     dataPath = "/pikachu/data/actualbudget";
+    reverseProxy = {
+      enable = true;
+      host = "budget.alexion.dev";
+      backend = "http://10.23.20.42:5006";
+    };
+  };
+
+  guests.reverse-proxy = {
+    enable = true;
+    vlan = 20;
+    mac = "02:98:64:5a:07:4f";
   };
 
   guests.copyparty = {
@@ -86,6 +97,12 @@
     vlan = 20;
     mac = "02:23:20:39:23:01";
     statePath = "/pikachu/data/copyparty";
+    reverseProxy = {
+      enable = true;
+      host = "files.alexion.dev";
+      backend = "http://10.23.20.126:3923";
+      trustedSources = [ "10.23.20.109/32" ];
+    };
     volumes = {
       "/inbox" = {
         hostPath = "/pikachu/__inbox";

lib/default.nix

@@ -10,14 +10,12 @@ let
     genAttrs
     flatten
     hasSuffix
-    escapeShellArg
     mapAttrsToList
     ;
 
   serviceIdentityRegistry = import ./service-identities.nix { inherit lib; };
+  reverseProxyRoutes = import ./reverse-proxy-routes.nix { inherit lib; };
 
-  # Recursively collect every `.nix` file under `dir` as a flat list, for a
-  # module's `imports`.
   collectNixFiles =
     dir:
     flatten (
@@ -35,32 +33,23 @@ let
       ) (builtins.readDir dir)
     );
 
-  # The special arguments every configuration is evaluated with, host and guest
-  # interior alike.
   specialArgs = {
     inherit inputs;
     my = self.lib;
   };
 
-  # The name of a tagged VLAN's bridge, kept here as the one definition of a
-  # convention shared across the flake.
   bridgeName = id: "br-vlan${toString id}";
 
-  # A guest with no operator-set MAC derives a stable one from its namespace path.
-  # The first octet 02 marks the address locally-administered and unicast.
-  # The rest is a slice of the path's hash.
-  # The same guest therefore always lands on the same address, which the operator can reserve at the router.
-  deriveMac =
-    name:
-    let
-      hash = builtins.hashString "sha256" name;
-      octet = i: builtins.substring (i * 2) 2 hash;
-    in
-    lib.concatStringsSep ":" ([ "02" ] ++ map octet [ 0 1 2 3 4 ]);
+  guests = import ./guests.nix {
+    inherit
+      lib
+      self
+      specialArgs
+      bridgeName
+      reverseProxyRoutes
+      ;
+  };
 
-  # Build one host: every module and every guest is imported unconditionally
-  # (inert until its `enable` flag is set), alongside chaotic, the host base,
-  # and the host's own directory.
   mkHost =
     {
       hostName,
@@ -82,379 +71,6 @@ let
         ];
     };
 
-  # Build a guest: a module-shaped definition whose body realizes its interior
-  # as a nested container standing on the guest-base, keyed by its namespace path.
-  # `name` is the dotted namespace under `guests.` and `interior` is an extra
-  # module merged into the container alongside the guest-base.
-  guest =
-    {
-      name,
-      interior ? { },
-    }:
-    { config, lib, ... }:
-    let
-      optionPath = [ "guests" ] ++ lib.splitString "." name;
-      cfg = lib.getAttrFromPath optionPath config;
-      machineName = lib.replaceStrings [ "." ] [ "-" ] name;
-
-      networked = cfg.vlan != null;
-
-      # Host paths the operator maps into the guest, keyed by their in-guest path.
-      userMounts = lib.mapAttrs (_guestPath: m: {
-        inherit (m) hostPath;
-        isReadOnly = m.readOnly;
-      }) cfg.mounts;
-
-      # Each named secret bind-mounted read-only at the same `/run/secrets/<name>`
-      # path it holds on the host.
-      # No ownership is set here, since the container's one-to-one identity map
-      # carries the host file's owner through unchanged.
-      secretMounts = lib.listToAttrs (
-        map (
-          name:
-          let
-            path = config.sops.secrets.${name}.path;
-          in
-          lib.nameValuePair path {
-            hostPath = path;
-            isReadOnly = true;
-          }
-        ) cfg.secrets
-      );
-
-      # An in-guest path claimed by both a mount and a secret, which the merge
-      # below would otherwise resolve silently in the secret's favour.
-      mountCollisions = lib.attrNames (builtins.intersectAttrs userMounts secretMounts);
-
-      # The resource caps the operator places on the guest's unit, dropping any
-      # left unset so systemd keeps its uncapped default for those.
-      limitConfig = lib.filterAttrs (_: v: v != null) {
-        MemoryMax = cfg.limits.memory;
-        CPUQuota = cfg.limits.cpu;
-        TasksMax = cfg.limits.tasksMax;
-      };
-
-      createdMounts = lib.filterAttrs (_guestPath: m: m.create != null) cfg.mounts;
-      mountCreateScript = lib.concatStringsSep "\n" (
-        mapAttrsToList (
-          _guestPath: m:
-          let
-            create = m.create;
-          in
-          ''
-            ${config.system.path}/bin/install -d -o ${escapeShellArg (toString create.owner)} -g ${escapeShellArg create.group} -m ${escapeShellArg create.mode} ${escapeShellArg m.hostPath}
-          ''
-        ) createdMounts
-      );
-
-      # A networked guest owns its bridged interface through its own networkd, the only stable MAC pin for a nested container.
-      # The interface is eth0, the name a nested container gives its bridged veth.
-      # It takes the placement MAC, and the static address or DHCP when that is unset.
-      guestNet =
-        { lib, ... }:
-        {
-          config = lib.mkIf networked {
-            networking.useNetworkd = true;
-
-            # networkd default-enables resolved, which owns the guest's resolv.conf.
-            # The nested-container default of inheriting the host's file conflicts with that, so the guest keeps its own.
-            networking.useHostResolvConf = false;
-
-            systemd.network.networks."20-eth0" = {
-              matchConfig.Name = "eth0";
-              linkConfig.MACAddress = cfg.mac;
-              networkConfig = lib.mkIf (cfg.address == null) { DHCP = "yes"; };
-              address = lib.mkIf (cfg.address != null) [ cfg.address ];
-            };
-          };
-        };
-    in
-    {
-      options = lib.setAttrByPath optionPath {
-        enable = lib.mkEnableOption "the ${name} guest, run in its own nested container";
-        backend = lib.mkOption {
-          type = lib.types.enum [
-            "container"
-            "microvm"
-          ];
-          default = "container";
-          description = ''
-            How the guest is realized. `container` runs the guest as a
-            systemd-nspawn nested container. `microvm` is reserved for a future
-            hard-isolation backend and is not built yet.
-          '';
-        };
-        vlan = lib.mkOption {
-          type = lib.types.nullOr (lib.types.ints.between 1 4094);
-          default = null;
-          example = 10;
-          description = ''
-            The tagged VLAN this guest lives on. The guest attaches to its host's
-            `br-vlan<id>` bridge for that VLAN. Left null, the guest keeps a
-            private network with no bridge attachment. The id must be one of the
-            host's `modules.network.vlans`.
-          '';
-        };
-        mac = lib.mkOption {
-          type = lib.types.str;
-          default = deriveMac name;
-          defaultText = lib.literalMD "a stable address derived from the guest's namespace path";
-          example = "bc:24:11:00:00:01";
-          description = ''
-            The guest's MAC address on its VLAN, pinned inside the guest by its
-            own networkd. Set it to reuse an existing address so a router's DHCP
-            reservation keeps working. Left unset, a stable address is derived
-            from the guest's namespace path in the locally-administered range.
-          '';
-        };
-        address = lib.mkOption {
-          type = lib.types.nullOr lib.types.str;
-          default = null;
-          example = "10.0.10.5/24";
-          description = ''
-            The guest's static address, in CIDR form, on its VLAN. Left null, the
-            guest takes its address by DHCP, keeping IP management at the router.
-          '';
-        };
-        mounts = lib.mkOption {
-          type = lib.types.attrsOf (
-            lib.types.submodule {
-              options = {
-                hostPath = lib.mkOption {
-                  type = lib.types.str;
-                  example = "/srv/media";
-                  description = "The path on the host bind-mounted into the guest.";
-                };
-                readOnly = lib.mkOption {
-                  type = lib.types.bool;
-                  default = false;
-                  description = ''
-                    Mount the path read-only. Read-write by default, since a
-                    service must write to the pool data it owns.
-                  '';
-                };
-                create = lib.mkOption {
-                  type = lib.types.nullOr (lib.types.submodule {
-                    options = {
-                      type = lib.mkOption {
-                        type = lib.types.enum [ "directory" ];
-                        default = "directory";
-                        description = "Host path type to create before the guest starts.";
-                      };
-                      owner = lib.mkOption {
-                        type = lib.types.oneOf [
-                          lib.types.str
-                          lib.types.ints.positive
-                        ];
-                        description = "Owner assigned to the created host path.";
-                      };
-                      group = lib.mkOption {
-                        type = lib.types.str;
-                        description = "Group assigned to the created host path.";
-                      };
-                      mode = lib.mkOption {
-                        type = lib.types.str;
-                        example = "0770";
-                        description = "Mode assigned to the created host path.";
-                      };
-                    };
-                  });
-                  default = null;
-                  description = ''
-                    Opt-in host path creation before the guest starts. Existing
-                    paths are left enabled unless this is set, so served storage
-                    roots can still be required to exist explicitly.
-                  '';
-                };
-              };
-            }
-          );
-          default = { };
-          example = lib.literalExpression ''
-            {
-              "/data/media" = { hostPath = "/srv/media"; };
-              "/data/config" = {
-                hostPath = "/srv/config/jellyfin";
-                readOnly = true;
-              };
-            }
-          '';
-          description = ''
-            Host paths bind-mounted into the guest, keyed by the path they appear
-            at inside the guest, so a guest sees exactly the data it should at any
-            granularity — a single folder or a whole pool. Each mount is
-            read-write unless `readOnly` is set.
-          '';
-        };
-        secrets = lib.mkOption {
-          type = lib.types.listOf lib.types.str;
-          default = [ ];
-          example = [ "jellyfin-api-key" ];
-          description = ''
-            Names of the secrets this guest needs. The host is the sole
-            decryptor: it decrypts each named secret from its own sops files and
-            bind-mounts the plaintext file into the guest read-only at
-            `/run/secrets/<name>`, the same path it would occupy on a host, so a
-            service reads its credentials at a predictable location. The guest
-            names the files it wants and receives exactly those. It holds no age
-            key and decrypts nothing itself. Ownership carries across unchanged,
-            since the container maps ids one to one, so a secret owned by a uid on
-            the host is owned by that same uid inside the guest.
-          '';
-        };
-        limits = {
-          memory = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "2G";
-            description = ''
-              Cap on the guest's memory, applied to its unit as `MemoryMax`.
-              Accepts systemd size suffixes such as `512M` or `2G`. Left null,
-              the guest's memory is uncapped.
-            '';
-          };
-          cpu = lib.mkOption {
-            type = lib.types.nullOr lib.types.str;
-            default = null;
-            example = "150%";
-            description = ''
-              Cap on the guest's CPU, applied to its unit as `CPUQuota`, where
-              `100%` is one full core. Left null, the guest's CPU is uncapped.
-            '';
-          };
-          tasksMax = lib.mkOption {
-            type = lib.types.nullOr lib.types.ints.positive;
-            default = null;
-            example = 512;
-            description = ''
-              Cap on the number of processes and threads the guest may spawn,
-              applied to its unit as `TasksMax`. Left null, the task count is
-              uncapped.
-            '';
-          };
-        };
-        nesting = lib.mkOption {
-          type = lib.types.bool;
-          default = false;
-          description = ''
-            Grant the guest's interior the prerequisites to run Podman or other
-            OCI containers of its own. Off by default, so a guest cannot nest
-            containers. On, the guest's container gains the network-administration
-            capability its container runtime uses to build bridges and firewall
-            rules, along with the tun and fuse device nodes such a runtime reaches
-            for, so the interior's `virtualisation.oci-containers` works with
-            Podman as its default runtime.
-          '';
-        };
-        autoStart = lib.mkOption {
-          type = lib.types.bool;
-          default = true;
-          description = ''
-            Start the guest at boot. On by default. Disabled, the guest stays
-            defined and can be started on demand, but does not come up at boot.
-          '';
-        };
-      };
-
-      config = lib.mkIf cfg.enable {
-        # Declared here so the host is the one that decrypts each named secret.
-        # The guest carries no age key and decrypts nothing of its own.
-        sops.secrets = lib.genAttrs cfg.secrets (_: { });
-
-        assertions = [
-          {
-            assertion = mountCollisions == [ ];
-            message = ''
-              guests.${name} maps a mount at ${lib.concatStringsSep ", " mountCollisions}, colliding with a secret bind-mounted at the same path. Rename the mount or the secret so each in-guest path is used once.
-            '';
-          }
-          {
-            assertion = cfg.backend == "container";
-            message = ''
-              guests.${name}.backend = "${cfg.backend}" is not implemented. Only the "container" backend is built; "microvm" is reserved for future work.
-            '';
-          }
-          {
-            assertion = !networked || lib.elem cfg.vlan config.modules.network.vlans;
-            message = ''
-              guests.${name}.vlan = ${toString cfg.vlan} is not among its host's modules.network.vlans (${lib.concatMapStringsSep ", " toString config.modules.network.vlans}). Declare the VLAN on the host or correct the guest's placement.
-            '';
-          }
-        ];
-
-        # The operator's resource caps land on the guest's own unit, which a
-        # networked guest also orders after the bridge its veth enslaves to at
-        # start, since the container backend orders the unit after the network
-        # is up but not after that specific bridge existing.
-        systemd.services."container@${machineName}" = lib.mkIf (cfg.backend == "container") (
-          lib.mkMerge [
-            {
-              serviceConfig = limitConfig;
-              preStart = lib.mkIf (createdMounts != { }) mountCreateScript;
-            }
-            (lib.mkIf networked (
-              let
-                bridgeDevice = "sys-subsystem-net-devices-${lib.replaceStrings [ "-" ] [ "\\x2d" ] (bridgeName cfg.vlan)}.device";
-              in
-              {
-                after = [ bridgeDevice ];
-                wants = [ bridgeDevice ];
-              }
-            ))
-          ]
-        );
-
-        containers.${machineName} = lib.mkIf (cfg.backend == "container") {
-          autoStart = cfg.autoStart;
-
-          # The guest gets its own network namespace, so its services — its own
-          # sshd included — never contend with the host's.
-          privateNetwork = lib.mkDefault true;
-
-          # A networked guest's veth is enslaved to the VLAN's bridge, making it
-          # a first-class L2 citizen on that segment.
-          hostBridge = lib.mkIf networked (bridgeName cfg.vlan);
-
-          # The container shares the host's uid and gid space one to one.
-          # A guest process writing as the shared storage group then lands on a bind-mounted pool as that same group, with no permission juggling.
-          # A private-user mapping would shift the ids and reintroduce those errors, so it stays off.
-          privateUsers = lib.mkDefault "no";
-
-          # A nesting guest runs Podman or other OCI containers in its interior.
-          # The network-administration capability lets that runtime build its
-          # bridges and firewall rules.
-          # The tun and fuse device nodes are what it reaches for to network
-          # those containers and back their overlay storage.
-          # The remaining prerequisite, a delegated cgroup subtree for the
-          # runtime to manage, the container backend already grants every guest.
-          additionalCapabilities = lib.optionals cfg.nesting [ "CAP_NET_ADMIN" ];
-          allowedDevices = lib.optionals cfg.nesting [
-            {
-              node = "/dev/net/tun";
-              modifier = "rwm";
-            }
-            {
-              node = "/dev/fuse";
-              modifier = "rwm";
-            }
-          ];
-
-          bindMounts = userMounts // secretMounts;
-
-          inherit specialArgs;
-
-          config = {
-            imports = [
-              (self + "/guest.nix")
-              guestNet
-              interior
-            ];
-          };
-        };
-      };
-    };
-
-  # Discover every host (a subdirectory of `hostsDir`) and build each one.
   mkHosts =
     hostsDir:
     let
@@ -467,9 +83,12 @@ in
     collectNixFiles
     mkHost
     mkHosts
-    guest
     bridgeName
+    reverseProxyRoutes
     ;
+
+  inherit (guests) deriveMac guest;
+
   inherit (serviceIdentityRegistry) serviceUid;
   serviceIdentities = serviceIdentityRegistry.identities;
 }

lib/guests.nix

@@ -0,0 +1,358 @@
+{
+  lib,
+  self,
+  specialArgs,
+  bridgeName,
+  reverseProxyRoutes,
+}:
+let
+  inherit (lib) escapeShellArg mapAttrsToList;
+
+  deriveMac =
+    name:
+    let
+      hash = builtins.hashString "sha256" name;
+      octet = i: builtins.substring (i * 2) 2 hash;
+    in
+    lib.concatStringsSep ":" ([ "02" ] ++ map octet [ 0 1 2 3 4 ]);
+
+  guest =
+    {
+      name,
+      interior ? { },
+    }:
+    { config, lib, ... }:
+    let
+      optionPath = [ "guests" ] ++ lib.splitString "." name;
+      cfg = lib.getAttrFromPath optionPath config;
+      machineName = lib.replaceStrings [ "." ] [ "-" ] name;
+
+      networked = cfg.vlan != null;
+
+      userMounts = lib.mapAttrs (_guestPath: m: {
+        inherit (m) hostPath;
+        isReadOnly = m.readOnly;
+      }) cfg.mounts;
+
+      secretMounts = lib.listToAttrs (
+        map (
+          name:
+          let
+            path = config.sops.secrets.${name}.path;
+          in
+          lib.nameValuePair path {
+            hostPath = path;
+            isReadOnly = true;
+          }
+        ) cfg.secrets
+      );
+
+      mountCollisions = lib.attrNames (builtins.intersectAttrs userMounts secretMounts);
+
+      limitConfig = lib.filterAttrs (_: v: v != null) {
+        MemoryMax = cfg.limits.memory;
+        CPUQuota = cfg.limits.cpu;
+        TasksMax = cfg.limits.tasksMax;
+      };
+
+      createdMounts = lib.filterAttrs (_guestPath: m: m.create != null) cfg.mounts;
+      mountCreateScript = lib.concatStringsSep "\n" (
+        mapAttrsToList (
+          _guestPath: m:
+          let
+            create = m.create;
+          in
+          ''
+            ${config.system.path}/bin/install -d -o ${escapeShellArg (toString create.owner)} -g ${escapeShellArg create.group} -m ${escapeShellArg create.mode} ${escapeShellArg m.hostPath}
+          ''
+        ) createdMounts
+      );
+
+      guestNet =
+        { lib, ... }:
+        {
+          config = lib.mkIf networked {
+            networking.useNetworkd = true;
+            networking.useHostResolvConf = false;
+
+            systemd.network.networks."20-eth0" = {
+              matchConfig.Name = "eth0";
+              linkConfig.MACAddress = cfg.mac;
+              networkConfig = lib.mkIf (cfg.address == null) { DHCP = "yes"; };
+              address = lib.mkIf (cfg.address != null) [ cfg.address ];
+            };
+          };
+        };
+    in
+    {
+      options = lib.setAttrByPath optionPath {
+        enable = lib.mkEnableOption "the ${name} guest, run in its own nested container";
+        backend = lib.mkOption {
+          type = lib.types.enum [
+            "container"
+            "microvm"
+          ];
+          default = "container";
+          description = ''
+            How the guest is realized. `container` runs the guest as a
+            systemd-nspawn nested container. `microvm` is reserved for a future
+            hard-isolation backend and is not built yet.
+          '';
+        };
+        vlan = lib.mkOption {
+          type = lib.types.nullOr (lib.types.ints.between 1 4094);
+          default = null;
+          example = 10;
+          description = ''
+            The tagged VLAN this guest lives on. The guest attaches to its host's
+            `br-vlan<id>` bridge for that VLAN. Left null, the guest keeps a
+            private network with no bridge attachment. The id must be one of the
+            host's `modules.network.vlans`.
+          '';
+        };
+        mac = lib.mkOption {
+          type = lib.types.str;
+          default = deriveMac name;
+          defaultText = lib.literalMD "a stable address derived from the guest's namespace path";
+          example = "bc:24:11:00:00:01";
+          description = ''
+            The guest's MAC address on its VLAN, pinned inside the guest by its
+            own networkd. Set it to reuse an existing address so a router's DHCP
+            reservation keeps working. Left unset, a stable address is derived
+            from the guest's namespace path in the locally-administered range.
+          '';
+        };
+        address = lib.mkOption {
+          type = lib.types.nullOr lib.types.str;
+          default = null;
+          example = "10.0.10.5/24";
+          description = ''
+            The guest's static address, in CIDR form, on its VLAN. Left null, the
+            guest takes its address by DHCP, keeping IP management at the router.
+          '';
+        };
+        reverseProxy = reverseProxyRoutes.mkRouteOptions {
+          subject = "guest route";
+          enableDefault = false;
+        };
+        mounts = lib.mkOption {
+          type = lib.types.attrsOf (
+            lib.types.submodule {
+              options = {
+                hostPath = lib.mkOption {
+                  type = lib.types.str;
+                  example = "/srv/media";
+                  description = "The path on the host bind-mounted into the guest.";
+                };
+                readOnly = lib.mkOption {
+                  type = lib.types.bool;
+                  default = false;
+                  description = ''
+                    Mount the path read-only. Read-write by default, since a
+                    service must write to the pool data it owns.
+                  '';
+                };
+                create = lib.mkOption {
+                  type = lib.types.nullOr (lib.types.submodule {
+                    options = {
+                      type = lib.mkOption {
+                        type = lib.types.enum [ "directory" ];
+                        default = "directory";
+                        description = "Host path type to create before the guest starts.";
+                      };
+                      owner = lib.mkOption {
+                        type = lib.types.oneOf [
+                          lib.types.str
+                          lib.types.ints.positive
+                        ];
+                        description = "Owner assigned to the created host path.";
+                      };
+                      group = lib.mkOption {
+                        type = lib.types.str;
+                        description = "Group assigned to the created host path.";
+                      };
+                      mode = lib.mkOption {
+                        type = lib.types.str;
+                        example = "0770";
+                        description = "Mode assigned to the created host path.";
+                      };
+                    };
+                  });
+                  default = null;
+                  description = ''
+                    Opt-in host path creation before the guest starts. Existing
+                    paths are left enabled unless this is set, so served storage
+                    roots can still be required to exist explicitly.
+                  '';
+                };
+              };
+            }
+          );
+          default = { };
+          example = lib.literalExpression ''
+            {
+              "/data/media" = { hostPath = "/srv/media"; };
+              "/data/config" = {
+                hostPath = "/srv/config/jellyfin";
+                readOnly = true;
+              };
+            }
+          '';
+          description = ''
+            Host paths bind-mounted into the guest, keyed by the path they appear
+            at inside the guest, so a guest sees exactly the data it should at any
+            granularity — a single folder or a whole pool. Each mount is
+            read-write unless `readOnly` is set.
+          '';
+        };
+        secrets = lib.mkOption {
+          type = lib.types.listOf lib.types.str;
+          default = [ ];
+          example = [ "jellyfin-api-key" ];
+          description = ''
+            Names of the secrets this guest needs. The host is the sole
+            decryptor: it decrypts each named secret from its own sops files and
+            bind-mounts the plaintext file into the guest read-only at
+            `/run/secrets/<name>`, the same path it would occupy on a host, so a
+            service reads its credentials at a predictable location. The guest
+            names the files it wants and receives exactly those. It holds no age
+            key and decrypts nothing itself. Ownership carries across unchanged,
+            since the container maps ids one to one, so a secret owned by a uid on
+            the host is owned by that same uid inside the guest.
+          '';
+        };
+        limits = {
+          memory = lib.mkOption {
+            type = lib.types.nullOr lib.types.str;
+            default = null;
+            example = "2G";
+            description = ''
+              Cap on the guest's memory, applied to its unit as `MemoryMax`.
+              Accepts systemd size suffixes such as `512M` or `2G`. Left null,
+              the guest's memory is uncapped.
+            '';
+          };
+          cpu = lib.mkOption {
+            type = lib.types.nullOr lib.types.str;
+            default = null;
+            example = "150%";
+            description = ''
+              Cap on the guest's CPU, applied to its unit as `CPUQuota`, where
+              `100%` is one full core. Left null, the guest's CPU is uncapped.
+            '';
+          };
+          tasksMax = lib.mkOption {
+            type = lib.types.nullOr lib.types.ints.positive;
+            default = null;
+            example = 512;
+            description = ''
+              Cap on the number of processes and threads the guest may spawn,
+              applied to its unit as `TasksMax`. Left null, the task count is
+              uncapped.
+            '';
+          };
+        };
+        nesting = lib.mkOption {
+          type = lib.types.bool;
+          default = false;
+          description = ''
+            Grant the guest's interior the prerequisites to run Podman or other
+            OCI containers of its own. Off by default, so a guest cannot nest
+            containers. On, the guest's container gains the network-administration
+            capability its container runtime uses to build bridges and firewall
+            rules, along with the tun and fuse device nodes such a runtime reaches
+            for, so the interior's `virtualisation.oci-containers` works with
+            Podman as its default runtime.
+          '';
+        };
+        autoStart = lib.mkOption {
+          type = lib.types.bool;
+          default = true;
+          description = ''
+            Start the guest at boot. On by default. Disabled, the guest stays
+            defined and can be started on demand, but does not come up at boot.
+          '';
+        };
+      };
+
+      config = lib.mkIf cfg.enable {
+        sops.secrets = lib.genAttrs cfg.secrets (_: { });
+
+        modules.reverse-proxy.routes.${machineName} = lib.mkIf cfg.reverseProxy.enable (
+          reverseProxyRoutes.routeFields cfg.reverseProxy
+        );
+
+        assertions = [
+          {
+            assertion = mountCollisions == [ ];
+            message = ''
+              guests.${name} maps a mount at ${lib.concatStringsSep ", " mountCollisions}, colliding with a secret bind-mounted at the same path. Rename the mount or the secret so each in-guest path is used once.
+            '';
+          }
+          {
+            assertion = cfg.backend == "container";
+            message = ''
+              guests.${name}.backend = "${cfg.backend}" is not implemented. Only the "container" backend is built; "microvm" is reserved for future work.
+            '';
+          }
+          {
+            assertion = !networked || lib.elem cfg.vlan config.modules.network.vlans;
+            message = ''
+              guests.${name}.vlan = ${toString cfg.vlan} is not among its host's modules.network.vlans (${lib.concatMapStringsSep ", " toString config.modules.network.vlans}). Declare the VLAN on the host or correct the guest's placement.
+            '';
+          }
+        ];
+
+        systemd.services."container@${machineName}" = lib.mkIf (cfg.backend == "container") (
+          lib.mkMerge [
+            {
+              serviceConfig = limitConfig;
+              preStart = lib.mkIf (createdMounts != { }) mountCreateScript;
+            }
+            (lib.mkIf networked (
+              let
+                bridgeDevice = "sys-subsystem-net-devices-${lib.replaceStrings [ "-" ] [ "\\x2d" ] (bridgeName cfg.vlan)}.device";
+              in
+              {
+                after = [ bridgeDevice ];
+                wants = [ bridgeDevice ];
+              }
+            ))
+          ]
+        );
+
+        containers.${machineName} = lib.mkIf (cfg.backend == "container") {
+          autoStart = cfg.autoStart;
+          privateNetwork = lib.mkDefault true;
+          hostBridge = lib.mkIf networked (bridgeName cfg.vlan);
+          privateUsers = lib.mkDefault "no";
+          additionalCapabilities = lib.optionals cfg.nesting [ "CAP_NET_ADMIN" ];
+          allowedDevices = lib.optionals cfg.nesting [
+            {
+              node = "/dev/net/tun";
+              modifier = "rwm";
+            }
+            {
+              node = "/dev/fuse";
+              modifier = "rwm";
+            }
+          ];
+
+          bindMounts = userMounts // secretMounts;
+
+          inherit specialArgs;
+
+          config = {
+            imports = [
+              (self + "/guest.nix")
+              guestNet
+              interior
+            ];
+          };
+        };
+      };
+    };
+in
+{
+  inherit deriveMac guest;
+}

lib/reverse-proxy-routes.nix

@@ -0,0 +1,77 @@
+{ lib }:
+let
+  mkRouteOptions =
+    {
+      name ? null,
+      subject ? "route",
+      enableDefault ? true,
+    }:
+    {
+      enable = lib.mkOption {
+        type = lib.types.bool;
+        default = enableDefault;
+        description = "Whether this reverse-proxy ${subject} is active.";
+      };
+
+      host = lib.mkOption (
+        {
+          type = lib.types.str;
+          description = "Primary hostname served by this reverse-proxy ${subject}.";
+        }
+        // lib.optionalAttrs (name != null) {
+          default = name;
+          defaultText = lib.literalMD "the route attribute name";
+        }
+      );
+
+      aliases = lib.mkOption {
+        type = lib.types.listOf lib.types.str;
+        default = [ ];
+        description = "Additional hostnames served by this reverse-proxy ${subject}.";
+      };
+
+      path = lib.mkOption {
+        type = lib.types.str;
+        default = "/";
+        description = "URL path prefix proxied by this reverse-proxy ${subject}.";
+      };
+
+      backend = lib.mkOption {
+        type = lib.types.str;
+        description = "Full HTTP backend URL that receives proxied traffic.";
+      };
+
+      tls = lib.mkOption {
+        type = lib.types.bool;
+        default = true;
+        description = "Whether to serve this reverse-proxy ${subject} with ACME-backed TLS.";
+      };
+
+      websockets = lib.mkOption {
+        type = lib.types.bool;
+        default = false;
+        description = "Whether to enable websocket proxy headers for this reverse-proxy ${subject}.";
+      };
+    };
+
+  routeFields = route: {
+    inherit (route)
+      host
+      aliases
+      path
+      backend
+      tls
+      websockets
+      ;
+  };
+in
+{
+  inherit mkRouteOptions routeFields;
+
+  routeType = lib.types.submodule (
+    { name, ... }:
+    {
+      options = mkRouteOptions { inherit name; };
+    }
+  );
+}

modules/reverse-proxy.nix

@@ -0,0 +1,82 @@
+{ config, lib, my, ... }:
+let
+  cfg = config.modules.reverse-proxy;
+  inherit (my) reverseProxyRoutes;
+
+  enabledRoutes = lib.filterAttrs (_: route: route.enable) cfg.routes;
+  routesByHost = lib.groupBy (route: route.host) (lib.attrValues enabledRoutes);
+
+  rootRoutesByHost = lib.mapAttrs (
+    host: routes:
+    let
+      roots = builtins.filter (route: route.path == "/") routes;
+    in
+    if roots == [ ] then null else builtins.head roots
+  ) routesByHost;
+
+  hasDuplicatePaths = routes:
+    let
+      paths = map (route: route.path) routes;
+    in
+    lib.length paths != lib.length (lib.unique paths);
+
+  mkLocation = route: {
+    proxyPass = route.backend;
+    proxyWebsockets = route.websockets;
+  };
+
+  mkVirtualHost = host: routes:
+    let
+      rootRoute = rootRoutesByHost.${host};
+    in
+    lib.mkIf (rootRoute != null) {
+      forceSSL = rootRoute.tls;
+      enableACME = rootRoute.tls;
+      serverAliases = rootRoute.aliases;
+      locations = lib.listToAttrs (
+        map (route: lib.nameValuePair route.path (mkLocation route)) routes
+      );
+    };
+in
+{
+  options.modules.reverse-proxy = {
+    enable = lib.mkEnableOption "the Nginx reverse proxy route realizer";
+
+    routes = lib.mkOption {
+      type = lib.types.attrsOf reverseProxyRoutes.routeType;
+      default = { };
+      description = "Reverse-proxy route declarations keyed by stable route name.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    assertions =
+      lib.mapAttrsToList (host: rootRoute: {
+        assertion = rootRoute != null;
+        message = "modules.reverse-proxy.routes for ${host} must include a primary / route.";
+      }) rootRoutesByHost
+      ++ lib.mapAttrsToList (host: routes: {
+        assertion = !hasDuplicatePaths routes;
+        message = "modules.reverse-proxy.routes for ${host} must not declare the same path more than once.";
+      }) routesByHost;
+
+    networking.firewall.allowedTCPPorts = [
+      80
+      443
+    ];
+
+    security.acme = {
+      acceptTerms = true;
+      defaults.email = "contact@alexion.dev";
+    };
+
+    services.nginx = {
+      enable = true;
+      recommendedGzipSettings = true;
+      recommendedOptimisation = true;
+      recommendedProxySettings = true;
+      recommendedTlsSettings = true;
+      virtualHosts = lib.mapAttrs mkVirtualHost routesByHost;
+    };
+  };
+}

modules/services/actualbudget.nix

@@ -40,6 +40,7 @@ in
       default = "storage";
       description = "Group account that owns Actual Budget's writable state.";
     };
+
   };
 
   config = lib.mkIf cfg.enable {

modules/services/copyparty.nix

@@ -48,6 +48,14 @@ let
     ''}
   '';
 
+  renderTrustedSource = source: "  xff-src: ${source}";
+
+  renderedReverseProxy = lib.optionalString cfg.reverseProxy.enable ''
+      rproxy: 1
+      xff-hdr: x-forwarded-for
+    ${lib.concatStringsSep "\n" (map renderTrustedSource cfg.reverseProxy.trustedSources)}
+  '';
+
   renderedVolumes = lib.concatStringsSep "\n" (lib.mapAttrsToList renderVolume cfg.volumes);
 
   configScript = pkgs.writeShellScript "copyparty-config" ''
@@ -68,7 +76,7 @@ let
       ses-db: ${cfg.stateDir}/sessions.db
       chpw-db: ${cfg.stateDir}/chpw.json
       shr-db: ${cfg.stateDir}/shares.db
-
+    ${renderedReverseProxy}
     [accounts]
       ${cfg.accountName}: $password
 
@@ -128,6 +136,16 @@ in
       default = { };
       description = "Copyparty volumes keyed by their URL path.";
     };
+
+    reverseProxy = {
+      enable = lib.mkEnableOption "reverse-proxy trust settings for Copyparty";
+
+      trustedSources = lib.mkOption {
+        type = lib.types.listOf lib.types.str;
+        default = [ ];
+        description = "IP ranges that may supply Copyparty's forwarded client IP header.";
+      };
+    };
   };
 
   config = lib.mkIf cfg.enable {
@@ -136,6 +154,10 @@ in
         assertion = cfg.volumes != { };
         message = "modules.services.copyparty.volumes must declare at least one served volume.";
       }
+      {
+        assertion = !cfg.reverseProxy.enable || cfg.reverseProxy.trustedSources != [ ];
+        message = "modules.services.copyparty.reverseProxy.trustedSources must name at least one trusted proxy source when reverse-proxy support is enabled.";
+      }
     ];
 
     users.users.${cfg.user} = {

prototypes/copyparty-rproxy-config/run.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+bold=$'\033[1m'
+reset=$'\033[0m'
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/state" "$tmp/root"
+
+printf '%sQuestion%s\n' "$bold" "$reset"
+printf 'Does the proposed copyparty reverse-proxy config parse and make a proxied HTTPS-origin login-shaped request pass the CORS gate?\n\n'
+
+printf '%sNix-generated config fragment%s\n' "$bold" "$reset"
+config_script=$(nix eval --raw '.#nixosConfigurations.pikachu.config.containers.copyparty.config.systemd.services.copyparty.serviceConfig.ExecStartPre')
+awk '/\[global\]/{show=1} /\[accounts\]/{show=0} show {print}' "$config_script" | grep -E 'rproxy|xff-hdr|xff-src' || true
+
+pkg=$(nix eval --raw '.#nixosConfigurations.pikachu.config.containers.copyparty.config.modules.services.copyparty.package.outPath')
+
+make_conf() {
+  local file=$1 port=$2 rproxy=$3
+  cat > "$file" <<EOF
+[global]
+  i: 127.0.0.1
+  p: $port
+  usernames
+  http-only
+  no-crt
+  no-thumb
+  no-snap
+  no-rescan
+  ses-db: $tmp/state/sessions-$port.db
+  chpw-db: $tmp/state/chpw-$port.json
+  shr-db: $tmp/state/shares-$port.db
+$rproxy
+
+[accounts]
+  alexion: prototype-password
+
+[/]
+  $tmp/root
+  accs:
+    A: alexion
+EOF
+}
+
+start_server() {
+  local conf=$1 log=$2
+  "$pkg/bin/copyparty" -c "$conf" >"$log" 2>&1 &
+  local pid=$!
+  for _ in {1..50}; do
+    if grep -q 'listening' "$log"; then
+      printf '%s' "$pid"
+      return 0
+    fi
+    sleep 0.1
+  done
+  cat "$log"
+  kill "$pid" 2>/dev/null || true
+  return 1
+}
+
+request() {
+  local label=$1 port=$2 host=$3 proto=${4:-}
+  local headers="$tmp/$label.headers"
+  local body="$tmp/$label.body"
+  local args=(
+    -sS
+    -D "$headers"
+    -o "$body"
+    -X POST
+    -H "Host: $host"
+    -H 'Origin: https://files.alexion.dev'
+    -H 'X-Forwarded-For: 10.23.20.20'
+  )
+  if [[ -n "$proto" ]]; then
+    args+=(-H "X-Forwarded-Proto: $proto")
+  fi
+  curl "${args[@]}" "http://127.0.0.1:$port/?pw=alexion:prototype-password" >/dev/null || true
+  printf '%-24s %s %s\n' "$label" "$(head -1 "$headers" | tr -d '\r')" "$(head -1 "$body")"
+}
+
+rproxy_config='  rproxy: 1
+  xff-hdr: x-forwarded-for
+  xff-src: 127.0.0.1/32'
+make_conf "$tmp/rproxy.conf" 39234 "$rproxy_config"
+pid=$(start_server "$tmp/rproxy.conf" "$tmp/rproxy.log")
+
+printf '\n%sCORS gate probes%s\n' "$bold" "$reset"
+request with-forwarded-https 39234 files.alexion.dev https
+request missing-forwarded-proto 39234 files.alexion.dev
+request wrong-forwarded-host 39234 '10.23.20.126:3923' https
+
+kill "$pid" 2>/dev/null || true
+wait "$pid" 2>/dev/null || true
+
+printf '\n%sRelevant server log%s\n' "$bold" "$reset"
+grep -E 'cors-reject|POST|http405|got proxied request|untrusted source|listening' "$tmp/rproxy.log" || true
+
+printf '\n%sNginx proxy headers%s\n' "$bold" "$reset"
+toplevel=$(nix build --print-out-paths '.#nixosConfigurations.pikachu.config.containers.reverse-proxy.config.system.build.toplevel' --no-link)
+nginx_conf=$(readlink -f "$toplevel/etc/nginx/nginx.conf")
+include_path=$(awk '/server_name files\.alexion\.dev;/{in_server=1} in_server && /include .*recommended-proxy_set_header/{print $2; exit}' "$nginx_conf" | tr -d ';')
+cat "$include_path"