7feef4cc5d
mara on #651: "Dont default openFirewall to true." Flip the `openFirewall` default from `true` to `false` for all three modules that expose host-side ports: - `services.hyperhive.forge.openFirewall` (httpPort 3000 + sshPort 2222) - `services.hyperhive.gateway.openFirewall` (port 80) - `services.hyperhive.matrix.openFirewall` (httpPort 8008) Rationale: secure-by-default. With shared host netns, the host + every agent container reach these services via `localhost` regardless of the firewall — the open only matters for access from outside the host. Operators who want external reach now flip the bool explicitly: services.hyperhive.gateway.openFirewall = true; Each description updated to explain the new default + when to flip it (operator's browser, external git clients, federation announcement, etc.). Behind a host-level reverse proxy that handles TLS, leave off. Verified via `nix eval` on a clean stub config: - forge openFirewall = false - gateway openFirewall = false - matrix openFirewall = false - networking.firewall.allowedTCPPorts = [] (was: [80 2222 3000 8008]) Note: c0re's direct ports (7000/8000/8100-8999) are gated separately via #621 on `gateway.enable` — that gate stays; this PR only touches the per-module `openFirewall` knobs. Closes #651.
360 lines
16 KiB
Nix
360 lines
16 KiB
Nix
{
|
|
pkgs,
|
|
lib,
|
|
config,
|
|
...
|
|
}:
|
|
let
|
|
cfg = config.services.hyperhive.matrix;
|
|
hyperhiveDomain = config.services.hyperhive.domain;
|
|
effectiveServerName =
|
|
if cfg.serverName != null then cfg.serverName else "matrix.${hyperhiveDomain}";
|
|
in
|
|
{
|
|
# Private Matrix homeserver (matrix-tuwunel — the official conduwuit
|
|
# successor) for hyperhive agents, wrapped in a nixos-container so it
|
|
# doesn't fight any existing `services.matrix-*` the operator may
|
|
# already run on the host. Same shape as `nix/modules/hive-forge.nix`:
|
|
# shared host netns (`privateNetwork = false`) so agents reach it at
|
|
# `http://localhost:<httpPort>` (or via the configured server_name
|
|
# for federation), nixos-container only here for state + systemd-unit
|
|
# isolation.
|
|
#
|
|
# Container name `hive-matrix` (not `h-*`) so the lifecycle scanner
|
|
# ignores it; operator manages via the standard `nixos-container` CLI.
|
|
#
|
|
# Persistent state at `/var/lib/nixos-containers/hive-matrix/var/lib/
|
|
# matrix-tuwunel/` (survives container restart / host reboot). To
|
|
# wipe, destroy the container.
|
|
#
|
|
# Initial rollout (#548): federation enabled (needed for multi-hive
|
|
# swarms; trusted_servers starts empty so no actual federation traffic
|
|
# leaves until peers are explicitly listed), registration enabled via
|
|
# a `registration_token_file` known only to hive-c0re (so agents can't
|
|
# self-register without going through the coordinator), e2ee disabled
|
|
# per operator call (tracked for follow-up at #551).
|
|
#
|
|
# Provisioning model (matches `nix/modules/hive-forge.nix` shape):
|
|
# hive-c0re generates a 32-byte random `registration_token` on first
|
|
# boot, writes it to `/var/lib/hyperhive/matrix-register-token` (mode
|
|
# 0600, root-only), and bind-mounts that file read-only into the
|
|
# tuwunel container at the same path so tuwunel can read it via
|
|
# `registration_token_file`. hive-c0re then uses the token to register
|
|
# each agent account via the matrix-spec UIAA registration flow, and
|
|
# persists the returned `access_token` to `<agent-state>/matrix-token`
|
|
# so the agent's matrix MCP client can authenticate without ever
|
|
# seeing the shared registration token.
|
|
|
|
options.services.hyperhive.matrix = {
|
|
enable = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = false;
|
|
description = ''
|
|
Run hive-matrix — a private matrix-tuwunel homeserver (in a
|
|
nixos-container) for hyperhive agents. Off by default while
|
|
the integration phases in; flip to `true` once the operator
|
|
has set `services.hyperhive.domain` and is ready to onboard agents.
|
|
'';
|
|
};
|
|
|
|
package = lib.mkOption {
|
|
type = lib.types.package;
|
|
default = pkgs.matrix-tuwunel;
|
|
defaultText = lib.literalExpression "pkgs.matrix-tuwunel";
|
|
description = ''
|
|
matrix-tuwunel package to run inside the container. Defaults
|
|
to nixpkgs's `pkgs.matrix-tuwunel`. Override to pin a
|
|
specific upstream if you need an unreleased feature.
|
|
'';
|
|
};
|
|
|
|
serverName = lib.mkOption {
|
|
type = lib.types.nullOr lib.types.str;
|
|
default = null;
|
|
example = "chat.example.org";
|
|
description = ''
|
|
Matrix `server_name` — the host part of every user ID
|
|
(`@argus:<server_name>`) and room ID minted on this
|
|
homeserver. CRITICAL: must be stable from day one because
|
|
it's embedded irrevocably in the identifiers. Defaults to
|
|
`matrix.''${services.hyperhive.domain}` (always a subdomain — keeps
|
|
the root domain free for the dashboard or forge). Override
|
|
here only if you need a name that doesn't follow the
|
|
`matrix.<domain>` shape.
|
|
'';
|
|
};
|
|
|
|
httpPort = lib.mkOption {
|
|
type = lib.types.port;
|
|
default = 8008;
|
|
description = ''
|
|
TCP port tuwunel serves the matrix client-server API on.
|
|
Default 8008 is the matrix-spec well-known port. Sits
|
|
outside hyperhive's claimed ranges (dashboard 7000, manager
|
|
8000, sub-agents 8100..8999). Federation listens on
|
|
`federationPort` separately.
|
|
'';
|
|
};
|
|
|
|
openFirewall = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = false;
|
|
example = true;
|
|
description = ''
|
|
Open `httpPort` in the host firewall. Off by default (#651,
|
|
secure-by-default): the homeserver is reachable from the
|
|
host + every agent container via `localhost` either way
|
|
(shared netns), so the firewall open only matters for
|
|
access from outside the host. Flip to `true` when announcing
|
|
the homeserver to other hives or when an external matrix
|
|
client needs to reach the client-server API directly.
|
|
|
|
Note: federation (the matrix-spec well-known port 8448) is
|
|
intentionally not opened here. tuwunel serves the federation
|
|
API on the same `httpPort` as the client-server API by
|
|
default; reaching it on 8448 requires either binding tuwunel
|
|
to that port explicitly OR a reverse-proxy + `.well-known/
|
|
matrix/server` delegation, neither of which lives in this
|
|
module. Add that proxy config alongside whatever serves your
|
|
dashboard or forge on 443.
|
|
'';
|
|
};
|
|
|
|
trustedServers = lib.mkOption {
|
|
type = lib.types.listOf lib.types.str;
|
|
default = [ ];
|
|
example = [ "matrix.org" ];
|
|
description = ''
|
|
List of trusted matrix servers (homeservers whose signing
|
|
keys this server will fetch identity-server-style). Empty
|
|
by default — federation is enabled at the protocol level
|
|
but no peer is trusted until listed here, so the homeserver
|
|
is effectively closed until the operator declares hive
|
|
peers explicitly.
|
|
'';
|
|
};
|
|
|
|
maxRequestSize = lib.mkOption {
|
|
type = lib.types.ints.positive;
|
|
default = 20000000;
|
|
description = ''
|
|
Maximum size in bytes of a single matrix client request body.
|
|
Default 20 MB matches the matrix-spec recommendation for
|
|
media uploads + the upstream tuwunel default.
|
|
'';
|
|
};
|
|
|
|
registrationTokenFile = lib.mkOption {
|
|
type = lib.types.path;
|
|
default = "/var/lib/hyperhive/matrix-register-token";
|
|
description = ''
|
|
Host path to a file containing the matrix registration token
|
|
tuwunel reads to authorise new-account creation. The token is
|
|
generated automatically by `hive-c0re` on first boot (32-byte
|
|
random hex, mode 0600) and is bind-mounted read-only into the
|
|
tuwunel container at the same path. Agents never see this
|
|
token — hive-c0re uses it to provision per-agent accounts
|
|
and the agent only receives the resulting `access_token`.
|
|
Override only when integrating with externally-managed
|
|
registration tokens.
|
|
'';
|
|
};
|
|
|
|
gui = {
|
|
enable = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = cfg.enable;
|
|
defaultText = lib.literalExpression "config.services.hyperhive.matrix.enable";
|
|
description = ''
|
|
Serve a matrix web client (default `pkgs.fluffychat-web`) as
|
|
a static dist at `/matrix/` via the hive-gateway nginx
|
|
(#607 / #634). Defaults to whatever
|
|
`services.hyperhive.matrix.enable` is — turning on the
|
|
homeserver gives you the web client by default; set to
|
|
`false` explicitly to opt out of the GUI while keeping
|
|
the homeserver running for agents. Requires
|
|
`services.hyperhive.gateway.enable` (default on); when
|
|
gateway is off no one hosts the GUI and the
|
|
`M4TR1X →` dashboard tab is hidden.
|
|
|
|
fluffychat-web supports per-login server pick — point it at
|
|
the in-host tuwunel URL (`http://localhost:8008` by
|
|
default) the first time. The post-#15 nginx-front re-root
|
|
(`https://matrix.''${services.hyperhive.domain}`) is tracked
|
|
separately in #609.
|
|
'';
|
|
};
|
|
|
|
package = lib.mkOption {
|
|
type = lib.types.package;
|
|
default = pkgs.fluffychat-web.overrideAttrs (old: {
|
|
# fluffychat-web ships with `<base href="/">` baked into its
|
|
# index.html — flutter's `--base-href` build flag replaces
|
|
# that placeholder. Default upstream build is `--base-href "/"`
|
|
# which is wrong for hyperhive's `/matrix/` sub-path mount:
|
|
# the browser resolves relative asset paths (`Imaging.js`,
|
|
# `flutter.js`, `splash/*`) against the document ROOT,
|
|
# producing 404s for every asset (#634). Inject the right
|
|
# base-href into the actual `flutter build web` invocation
|
|
# via the upstream derivation's `flutterBuildFlags` string
|
|
# (the buildPhase is literally
|
|
# `flutter build web -v $flutterBuildFlags`). When subdomain
|
|
# routing lands (#609 — `matrix.${hyperhiveDomain}`), drop
|
|
# this override; upstream's `/` base-href is correct at the
|
|
# root of a dedicated subdomain.
|
|
flutterBuildFlags = (old.flutterBuildFlags or [ ]) ++ [
|
|
"--base-href"
|
|
"/matrix/"
|
|
];
|
|
});
|
|
defaultText = lib.literalMD "`pkgs.fluffychat-web` rebuilt with `--base-href /matrix/` via `flutterBuildFlags`.";
|
|
description = ''
|
|
Static web client dist to serve at `/matrix/`. Defaults to
|
|
`pkgs.fluffychat-web` rebuilt with `--base-href "/matrix/"`
|
|
so relative asset paths resolve under the sub-path mount
|
|
(#634). Override to swap for `hydrogen-web` (lightest),
|
|
`cinny` (no threads), `element-web` (heaviest, full
|
|
features), or an out-of-tree client dist — any replacement
|
|
also needs its `<base href>` aligned with the mount path.
|
|
'';
|
|
};
|
|
};
|
|
};
|
|
|
|
config = lib.mkIf cfg.enable {
|
|
# mara on #548: "there is no default, but it is required. add
|
|
# assertion." — fail eval with a helpful message rather than
|
|
# spawning a homeserver with a bogus server_name we can never
|
|
# change later. `services.hyperhive.domain` is host-wide; matrix derives
|
|
# the server_name from it (or from `cfg.serverName` if the
|
|
# operator wants to override).
|
|
assertions = [
|
|
{
|
|
assertion = hyperhiveDomain != null || cfg.serverName != null;
|
|
message = ''
|
|
services.hyperhive.matrix.enable = true requires either:
|
|
- services.hyperhive.domain set to your host's canonical domain
|
|
(recommended; shared with forge / dashboard), or
|
|
- services.hyperhive.matrix.serverName set explicitly.
|
|
|
|
The matrix server_name is embedded into every user ID and
|
|
room ID on this homeserver — it cannot be changed later
|
|
without losing every account and chat history. Pick a
|
|
stable hostname before enabling.
|
|
'';
|
|
}
|
|
];
|
|
|
|
# Pin the `tuwunel` group at a fixed GID on BOTH the host and the
|
|
# hive-matrix container. The registration token file lives on the
|
|
# host bind-mounted into the container; for tuwunel's non-root
|
|
# user inside the container to read it, the file gets `chown
|
|
# root:tuwunel` + mode `0640` in the activation script below. That
|
|
# ownership only works if the numeric GID resolves to the same
|
|
# name on both sides of the bind — without an explicit pin, the
|
|
# host's auto-allocated GID for `tuwunel` (if any) almost
|
|
# certainly wouldn't match the container's. 10042 sits well
|
|
# outside nixos's auto-allocated system-user range (200..399).
|
|
users.groups.tuwunel.gid = 10042;
|
|
|
|
# Generate the registration token at system activation time, BEFORE
|
|
# the hive-matrix container would otherwise start with an empty
|
|
# bind-mount target (argus nit on #565: nspawn creates an empty
|
|
# file when the host path is missing, tuwunel reads it as
|
|
# `registration_token_file=""` and rejects every registration
|
|
# until the next restart). Idempotent: only writes when the file
|
|
# doesn't exist. 32-byte hex = 64 chars, same shape hive-c0re's
|
|
# `matrix::ensure_register_token` would produce.
|
|
#
|
|
# Ownership: tuwunel inside the hive-matrix container runs as its
|
|
# own non-root user (nixpkgs's `services.matrix-tuwunel`), so a
|
|
# 0600 root-owned file denies it open(2) and tuwunel boots loop-
|
|
# fails with `Permission denied (os error 13)` (#644). Fix:
|
|
# `chown root:tuwunel` + `chmod 0640` so only the tuwunel group
|
|
# gains read access (no world-readable footgun, per mara). The
|
|
# `tuwunel` group GID is pinned to 10042 above so the host's name
|
|
# → number lookup matches what the container sees.
|
|
system.activationScripts.hive-matrix-register-token = lib.stringAfter [ "var" "users" ] ''
|
|
tokenFile=${lib.escapeShellArg (toString cfg.registrationTokenFile)}
|
|
if [ ! -s "$tokenFile" ]; then
|
|
mkdir -p "$(dirname "$tokenFile")"
|
|
head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > "$tokenFile"
|
|
echo >> "$tokenFile"
|
|
echo "hive-matrix: generated registration token at $tokenFile"
|
|
fi
|
|
# Always re-apply ownership + mode (covers existing 0600 root-
|
|
# owned files from pre-#644 deployments; `chown` + `chmod` are
|
|
# both idempotent).
|
|
chown root:tuwunel "$tokenFile"
|
|
chmod 0640 "$tokenFile"
|
|
'';
|
|
|
|
containers.hive-matrix = {
|
|
autoStart = true;
|
|
ephemeral = false;
|
|
# Share host netns — tuwunel's listeners look exactly like
|
|
# host-side services, no port-forward plumbing, and agent
|
|
# containers (also host netns) reach it via plain `localhost`.
|
|
privateNetwork = false;
|
|
# Read-only bind of the host-managed registration token so
|
|
# tuwunel can resolve `registration_token_file` to a real
|
|
# file inside the container. The activation script above
|
|
# ensures the host path exists with a valid 64-char hex token
|
|
# before any container starts, so the bind always finds real
|
|
# content (no first-boot empty-file race; argus #565 nit).
|
|
bindMounts.${cfg.registrationTokenFile} = {
|
|
hostPath = cfg.registrationTokenFile;
|
|
isReadOnly = true;
|
|
};
|
|
config =
|
|
{ ... }:
|
|
{
|
|
system.stateVersion = "26.05";
|
|
# Mirror the host's pinned `tuwunel` GID so the bind-mounted
|
|
# registration token (chowned `root:tuwunel` on the host)
|
|
# resolves to the same group inside the container. Without
|
|
# this pin nixos auto-allocates whatever's free, the two
|
|
# sides diverge, and tuwunel's user falls back to the
|
|
# "other" mode bits (= no read) on the file. See the host-
|
|
# side `users.groups.tuwunel.gid` above.
|
|
users.groups.tuwunel.gid = 10042;
|
|
services.matrix-tuwunel = {
|
|
enable = true;
|
|
package = cfg.package;
|
|
settings.global = {
|
|
server_name = effectiveServerName;
|
|
# `address` is `listOf nonEmptyStr` upstream (multi-bind
|
|
# support). Single-host bind goes through as a one-element list.
|
|
address = [ "0.0.0.0" ];
|
|
# `port` is `listOf port` upstream. Same shape.
|
|
port = [ cfg.httpPort ];
|
|
max_request_size = cfg.maxRequestSize;
|
|
# Federation enabled at the protocol level so swarms
|
|
# can be wired up later by extending `trustedServers`
|
|
# without a homeserver restart. Empty trusted_servers
|
|
# keeps it effectively closed until peers are listed.
|
|
allow_federation = true;
|
|
trusted_servers = cfg.trustedServers;
|
|
# Token-gated registration: hive-c0re holds the token,
|
|
# agents never see it. allow_registration must be true
|
|
# for the token flow to engage; the absent
|
|
# `yes_i_am_very_very_sure_…_open_registration_…` flag
|
|
# keeps the server closed to anyone without the token.
|
|
allow_registration = true;
|
|
registration_token_file = toString cfg.registrationTokenFile;
|
|
# E2EE disabled in initial rollout per operator call
|
|
# (#548) — re-enabling tracked at #551.
|
|
allow_encryption = false;
|
|
};
|
|
};
|
|
environment.systemPackages = [ cfg.package ];
|
|
};
|
|
};
|
|
|
|
networking.firewall = lib.mkIf cfg.openFirewall {
|
|
allowedTCPPorts = [
|
|
cfg.httpPort
|
|
];
|
|
};
|
|
};
|
|
}
|