hyperhive/nix/host-modules/swarm-ca.nix

# The swarm root CA: the anchor a whole swarm shares, and the issuer of
# each hive's own CA (which is where it gets used — see ./hive-tls.nix).
#
# One root rather than per-peer pinning, because cross-hive trust is then
# O(1): trust the root once and every present *and future* peer validates,
# instead of every hive having to name every other one.
#
# Two provisioning modes share ONE structure — what differs is who puts
# the artifacts on disk, never what the artifacts are. Which mode does
# what, and what moving between them costs:
# `docs/swarm/ca.md::Two provisioning modes, one structure`.
#
# ⚠️ Root key AND root cert are runtime files, never nix options. The key
# for the obvious reason; the cert as a consequence, and that one costs
# something real — nothing whose trust store is built at build time can
# name it: `docs/swarm/ca.md::Distributing the root`.
#
# ⚠️ This root does not issue the swarm's SERVICE certificates; there is no
# `swarm-services-ca` sub-CA under it. Those come out of the secret store's
# own `pki` mount, anchored on a root generated inside it (./swarm-bao.nix),
# and ./hive-tls.nix asks for them over the network instead of signing them
# here. This root has one job: the anchor each hive's own CA is issued under.
{
  lib,
  config,
  pkgs,
  ...
}:
let
  cfg = config.services.hyperhive.swarm.ca;
  hyperhiveCfg = config.services.hyperhive;

  # The subject CN is a label for a human reading a chain, not an
  # identity anything authenticates against. Fall through swarm name →
  # hive domain → a constant so a hive that has set neither still
  # evaluates; a missing `domain` is reported by its own assertion in
  # hive-network.nix, and shouldn't also surface here as a null.
  swarmLabel =
    if hyperhiveCfg.swarm.name != null then
      hyperhiveCfg.swarm.name
    else if hyperhiveCfg.domain != null then
      hyperhiveCfg.domain
    else
      "hyperhive";
in
{
  options.services.hyperhive.swarm.ca = {
    autoConfigure = lib.mkOption {
      type = lib.types.bool;
      default = false;
      example = true;
      description = ''
        Run the whole swarm CA on this one host: generate the swarm
        root when it is missing, and issue this hive's CA under it.

        `services.hyperhive.deploy.singleHostSwarm` turns this on as
        part of the all-on-one-box mode. Set it here directly to run the
        CA on a host that is not otherwise all-local.

        **Off by default, deliberately.** A swarm's services and its
        hives can live on different hosts, and this host has no way to
        tell whether it is the one holding the root — so the swarm CA
        is something an operator sets up, not something a host decides
        it is. Turn this on for an all-on-one-host deployment (dev
        boxes, single-hive swarms) and get the hierarchy for free.

        With it off, both artifacts are operator-provided: the root
        under `stateDir`, and this hive's CA under
        `services.hyperhive.deploy.hive-controller.tls.stateDir`. A hive
        given neither keeps the self-signed CA it has always had — it
        simply isn't part of a swarm's trust hierarchy, which is the
        correct outcome for a hive nobody has federated yet.
      '';
    };

    stateDir = lib.mkOption {
      type = lib.types.str;
      default = "/var/lib/swarm-ca";
      description = ''
        Host directory holding the swarm root CA: `root.pem` (the
        anchor, safe to distribute — copy it to this same path on every
        other host in the swarm) and `root-key.pem`
        (0600, the one file that must never reach the nix store or
        another host). The directory itself is 0700: nothing reads
        out of it but the hive CA issuance in `hive-tls.nix`.

        Moving the swarm CA to its own host is a matter of moving this
        directory and setting `autoConfigure = false` here.
      '';
    };

    validityDays = lib.mkOption {
      type = lib.types.int;
      default = 10950;
      description = ''
        Validity window of the swarm root CA in days (default ~30y).
        Deliberately long: the root must outlive the hive CAs it issued, or those chains
        expire out from under hives that are still perfectly happy with
        their own intermediate. Rotating a root is the one operation in
        this system with no partial-failure mode — it invalidates every
        peer at once, paced by the slowest peer's rebuild — so it is
        never automatic and this window is meant to be uneventful.
      '';
    };
  };

  config = lib.mkIf cfg.autoConfigure {
    systemd.services.swarm-ca = {
      description = "Generate the swarm root CA when absent";
      wantedBy = [ "multi-user.target" ];
      path = [ pkgs.openssl ];
      serviceConfig = {
        Type = "oneshot";
        RemainAfterExit = true;
        UMask = "0077";
        # Pin the journal identity (else it's the `script` store-path wrapper).
        SyslogIdentifier = "swarm-ca";
      };
      script = ''
        set -euo pipefail
        d=${lib.escapeShellArg cfg.stateDir}
        install -d -m 0700 "$d"

        root="$d/root.pem"
        rootk="$d/root-key.pem"

        # Note the asymmetry with the hive CA in hive-tls.nix, which
        # regenerates itself once expired: a root is never replaced
        # automatically, not even an expired one. Consumers hold this
        # cert, so replacing it is a swarm-wide flag day that wants an
        # operator running it deliberately, with both roots trusted
        # across the overlap.
        if [ -s "$root" ] && [ -s "$rootk" ]; then
          echo "swarm root CA already present at $root — leaving it alone"
          exit 0
        fi

        # Half a root is not a root. Generating a fresh key beside an
        # already-distributed cert (or the reverse) leaves every
        # consumer trusting an anchor that no longer signs anything —
        # and it would look like it worked.
        if [ -e "$root" ] || [ -e "$rootk" ]; then
          echo "swarm root CA half-provisioned ($root / $rootk) — refusing to generate over it" >&2
          exit 1
        fi

        echo "generating swarm root CA at $root"
        # pathlen:1 — the root signs hive CAs, which sign leaves. One
        # intermediate below the root and no deeper.
        openssl req -x509 -newkey rsa:4096 -nodes -sha256 \
          -days ${toString cfg.validityDays} \
          -keyout "$rootk" -out "$root" \
          -subj "/CN=swarm-ca ${swarmLabel}" \
          -addext "basicConstraints=critical,CA:TRUE,pathlen:1" \
          -addext "keyUsage=critical,keyCertSign,cRLSign"
        chmod 0600 "$rootk"
        chmod 0644 "$root"
      '';
    };
  };
}