From 39510246f06c6e77743ac4fd2a367fb6fc8849f6 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Sun, 11 Oct 2026 23:22:39 -0700 Subject: [PATCH] inbuxa join: the console and the webmail here, for a server elsewhere `inbuxa join https://mail.example.com --key KEY` installs the front ends on this machine for a mail server already running on another one. That server is reached only over its own HTTPS, with an API key a server administrator made in the console (--key -, or INBUXA_JOIN_KEY, keeps it out of the shell's history; it is never written down). Through it the front ends' addresses and a webmail client secret made here go into the server's inbuxa:FrontEnds (server #195), which registers their sign-in and allows the console's origin on every node, with no restart and nothing done by hand on that machine. It asks first, dry runs included, and refuses with the reason when the key is wrong, the server has no inbuxa:FrontEnds, it already lists other front ends (--replace), or its environment owns the webmail's secret. Then it installs the console and the webmail in containers with Caddy, registers them, exempts the webmail's address from the server's auto-ban (what its name resolves to, loopback for a loopback server, or --exempt-address), and checks that the server lets the console call it. A second join with the same addresses converges. The compose file learns a server elsewhere: the webmail reaches it at its address, and Caddy serves only the front ends' names. Container and host-server installs render as before. INBUXA_SERVER_BINARY installs a server build instead of the release wherever the server goes on the host, for testing a server change before it is released; e2e/vm/run.sh passes one in with SERVER_BINARY=. e2e/cases/join.sh: 24 checks on Debian 13 against a build of server #195, ending with a person signing in to the joined webmail. install-local, install-host, install-public, status-export and topology pass unchanged. --- README.md | 21 +- cmd/inbuxa/main.go | 150 ++++++++- e2e/cases/join.sh | 148 +++++++++ e2e/vm/run.sh | 6 + internal/apply/apply.go | 6 +- internal/apply/hostserver.go | 13 +- internal/apply/join.go | 314 +++++++++++++++++++ internal/apply/join_test.go | 120 +++++++ internal/compose/compose.go | 46 +++ internal/compose/compose_test.go | 34 ++ internal/compose/templates/Caddyfile.tmpl | 3 + internal/compose/templates/compose.yaml.tmpl | 21 +- internal/jmap/client.go | 4 + internal/jmap/frontends.go | 111 +++++++ internal/plan/plan.go | 26 ++ internal/state/state.go | 1 + 16 files changed, 1010 insertions(+), 14 deletions(-) create mode 100644 e2e/cases/join.sh create mode 100644 internal/apply/join.go create mode 100644 internal/apply/join_test.go create mode 100644 internal/jmap/frontends.go diff --git a/README.md b/README.md index 5ea4a80..d161a9a 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,19 @@ This is early. What is built: the proxy, and the unit will not start without a configuration file. The console and the webmail run in containers beside it, or not at all. +- **`join URL --key KEY`** -- the console and the webmail on this machine, + for a mail server already running at URL on another one. It reaches that + server only over its own HTTPS, with an API key a server administrator + made in the console (`--key -` reads it from standard input, and + `INBUXA_JOIN_KEY` keeps it out of the shell's history; it is never written + down). Through it the front ends' addresses go into the server's + `inbuxa:FrontEnds`, which registers their sign-in and lets the console + call the server from the browser, with no restart and nothing changed on + that machine by hand. It asks first, dry runs included, and refuses with + the reason when the key is wrong, the server is too old, or it already + lists other front ends (`--replace` to put these in their place). Needs a + server release newer than 2026.10.10.1. + - **`plan -f` / `apply -f` / `export`** -- a whole installation described in one file, however many machines. Each machine acts on its own part and prints the command to run on the others; it never reaches them. `plan` @@ -75,7 +88,7 @@ This is early. What is built: asked in a script whether it still matches itself. Not built yet: host installs of the console and the webmail, the terminal -interface, `join`, `upgrade`, `uninstall`, and moving the server between a +interface, `upgrade`, `uninstall`, and moving the server between a container and the host. The design is in the inbuxa specification (§6.1 and the installer draft); the phases are there too. @@ -116,12 +129,18 @@ is tested on a throwaway virtual machine rather than on anybody's desk: e2e/vm/run.sh e2e/cases/install-local.sh a whole suite, and signing in to it e2e/vm/run.sh e2e/cases/install-public.sh the same with real ports and certificates e2e/vm/run.sh e2e/cases/install-host.sh the server on the host, the rest beside it + e2e/vm/run.sh e2e/cases/join.sh front ends joined to a server elsewhere e2e/vm/run.sh e2e/cases/topology.sh growing and shrinking from a file e2e/vm/run.sh e2e/cases/status-export.sh intent against reality, and the file OLD_REF= e2e/vm/run.sh e2e/cases/upgrade-volumes.sh an install from before #5, upgraded e2e/vm/down.sh remove it +`SERVER_BINARY=path/to/inbuxa e2e/vm/run.sh …` installs a server build +instead of the release wherever a case installs the server on the host (the +installer's `INBUXA_SERVER_BINARY`), for testing a server change before it +is released. + Each case starts from a copy of the machine taken when it was new, so a run is free to break it and a failure is the installer's rather than the last run's leftovers. `e2e/vm/up.sh` needs qemu, KVM and xorriso; nothing needs diff --git a/cmd/inbuxa/main.go b/cmd/inbuxa/main.go index 7fb5f68..dacdfd7 100644 --- a/cmd/inbuxa/main.go +++ b/cmd/inbuxa/main.go @@ -9,11 +9,13 @@ package main import ( + "bufio" "context" "encoding/json" "flag" "fmt" "io" + "net" "os" "path/filepath" "runtime" @@ -35,6 +37,8 @@ var version = "dev" const usage = `inbuxa -- install the inbuxa suite on this machine inbuxa install [flags] install or converge (no flags: the interface) + inbuxa join URL [flags] the console and the webmail here, for a server + already running at URL inbuxa survey what this machine is, as the installer sees it inbuxa deps [--install] what is missing for a shape, and fix it inbuxa plan -f FILE what a topology file would change here @@ -63,6 +67,21 @@ install flags: --dry-run print the plan and stop --yes do not ask for confirmation +join flags: + --key KEY an API key made in the console by a server + administrator; "-" reads it from standard input. + INBUXA_JOIN_KEY works too, and keeps it out of + the shell's history + --console SHAPE container | skip (default: container) + --webmail SHAPE container | skip (default: container) + --domain NAME default: the server's name without its first label + --console-host, --webmail-host, --email, --proxy, --dir, --local, + --install-deps, --dry-run, --yes as for install + --replace put these front ends in place of others the + server already lists + --exempt-address IP the address the server sees the webmail at, when + it is not what the webmail's name resolves to + deps flags: --server/--console/--webmail SHAPE the shapes to work out the needs for --install do it, rather than only saying what it would do @@ -93,6 +112,8 @@ func main() { switch os.Args[1] { case "install": os.Exit(install(os.Args[2:])) + case "join": + os.Exit(join(os.Args[2:])) case "survey": os.Exit(survey()) case "deps": @@ -182,7 +203,7 @@ func install(args []string) int { return 1 } fmt.Println("\nChecking it works:") - problems := apply.Verify(context.Background(), res, + problems := apply.Verify(context.Background(), res, true, o.Shape(plan.Console) != plan.Skip, o.Shape(plan.Webmail) != plan.Skip, log) for _, why := range problems { fmt.Fprintln(os.Stderr, " problem: "+why) @@ -212,6 +233,133 @@ func install(args []string) int { return 0 } +// join installs the front ends here for a server elsewhere. The server is +// reached only over its own HTTPS, with an API key, never over SSH. +func join(args []string) int { + if len(args) == 0 || strings.HasPrefix(args[0], "-") { + fmt.Fprintln(os.Stderr, "which server? inbuxa join https://mail.example.com --key ...") + return 2 + } + serverURL := strings.TrimRight(args[0], "/") + if !strings.HasPrefix(serverURL, "https://") && !strings.HasPrefix(serverURL, "http://") { + serverURL = "https://" + serverURL + } + fs := flag.NewFlagSet("join", flag.ContinueOnError) + fs.Usage = func() { fmt.Print(usage) } + var ( + o plan.Options + key = fs.String("key", os.Getenv("INBUXA_JOIN_KEY"), "") + console = fs.String("console", "container", "") + webmail = fs.String("webmail", "container", "") + dryRun = fs.Bool("dry-run", false, "") + yes = fs.Bool("yes", false, "") + ) + fs.StringVar(&o.Domain, "domain", "", "") + fs.StringVar(&o.ConsoleHost, "console-host", "", "") + fs.StringVar(&o.WebmailHost, "webmail-host", "", "") + fs.StringVar(&o.ACMEEmail, "email", "", "") + fs.StringVar(&o.Proxy, "proxy", "", "") + fs.StringVar(&o.Dir, "dir", "", "") + fs.BoolVar(&o.Local, "local", false, "") + fs.BoolVar(&o.InstallDeps, "install-deps", false, "") + fs.BoolVar(&o.Replace, "replace", false, "") + fs.StringVar(&o.ExemptAddress, "exempt-address", "", "") + fs.StringVar(&o.ACMEDirectory, "acme-directory", "", "") + fs.StringVar(&o.ACMECARoot, "acme-ca-root", "", "") + if err := fs.Parse(args[1:]); err != nil { + return 2 + } + if *key == "-" { + line, err := bufio.NewReader(os.Stdin).ReadString('\n') + if err != nil && line == "" { + fmt.Fprintln(os.Stderr, "reading the key from standard input: "+err.Error()) + return 2 + } + *key = strings.TrimSpace(line) + } + if *key == "" { + fmt.Fprintln(os.Stderr, "an API key is needed: make one in the console (your account, API keys) and pass it with --key or INBUXA_JOIN_KEY") + return 2 + } + o.ServerURL = serverURL + if o.Domain == "" { + host := strings.TrimPrefix(strings.TrimPrefix(serverURL, "https://"), "http://") + host = strings.SplitN(strings.SplitN(host, "/", 2)[0], ":", 2)[0] + // A name gives its domain; an address gives none, and --domain + // (or --local) is needed then. + if net.ParseIP(host) == nil { + if _, rest, ok := strings.Cut(host, "."); ok && strings.Contains(rest, ".") { + o.Domain = rest + } else { + o.Domain = host + } + } + } + o.Choices = append(o.Choices, plan.Choice{Component: plan.Server, Shape: plan.Skip}) + for _, c := range []struct { + comp plan.Component + val string + }{{plan.Console, *console}, {plan.Webmail, *webmail}} { + s, err := shape(c.val) + if err != nil { + fmt.Fprintf(os.Stderr, "--%s: %v\n", c.comp, err) + return 2 + } + o.Choices = append(o.Choices, plan.Choice{Component: c.comp, Shape: s}) + } + + ctx := context.Background() + f := host.Survey(ctx) + p, err := plan.Build(f, o) + if err != nil { + fmt.Fprintln(os.Stderr, "cannot join as asked: "+err.Error()) + return 1 + } + fmt.Print(p.String()) + // The server is asked even on a dry run: it changes nothing, and a key + // that doesn't work or a front end it would replace is worth knowing + // before anything else. + fmt.Printf("\nAsking %s:\n", serverURL) + if err := apply.JoinCheck(ctx, p.Options, *key); err != nil { + fmt.Fprintln(os.Stderr, " "+err.Error()) + return 1 + } + fmt.Println(" the key works, and the server can take these front ends") + if *dryRun { + return 0 + } + if !*yes { + fmt.Fprintln(os.Stderr, "\nNothing has happened yet. Pass --yes to carry this out.") + return 1 + } + + fmt.Println("\nApplying:") + log := &printer{} + res, err := apply.Join(ctx, p, f, *key, log) + if err != nil { + fmt.Fprintln(os.Stderr, "\nstopped: "+err.Error()) + return 1 + } + fmt.Println("\nChecking it works:") + problems := apply.JoinVerify(ctx, res, + p.Options.Shape(plan.Console) != plan.Skip, p.Options.Shape(plan.Webmail) != plan.Skip, log) + for _, why := range problems { + fmt.Fprintln(os.Stderr, " problem: "+why) + } + fmt.Printf("\nDone. %s, joined to %s\n", res.Dir, serverURL) + if res.ConsoleURL != "" { + fmt.Printf(" console %s\n", res.ConsoleURL) + } + if res.WebmailURL != "" { + fmt.Printf(" webmail %s\n", res.WebmailURL) + } + fmt.Println(" The API key is not kept here; you can remove it in the console now.") + if len(problems) > 0 { + return 1 + } + return 0 +} + // printer is apply's log on the flag path: steps as lines, everything a // command says indented under the step that ran it. type printer struct{} diff --git a/e2e/cases/join.sh b/e2e/cases/join.sh new file mode 100644 index 0000000..460df96 --- /dev/null +++ b/e2e/cases/join.sh @@ -0,0 +1,148 @@ +#!/bin/bash +# SPDX-FileCopyrightText: 2026 Coffey Labs LLC +# SPDX-License-Identifier: AGPL-3.0-or-later +# +# inbuxa join: the console and the webmail on one machine, for a server +# installed on another. Two machines are played by one: the server is +# installed on its own, its install record is set aside so this looks like a +# machine without one, and the front ends are joined to it on loopback in a +# deployment directory of their own. +# +# What only a join proves is checked: the server learns the front ends' +# addresses over JMAP (inbuxa:FrontEnds), the console's origin is allowed, +# and a person signs in to the joined webmail with the secret made here -- +# which the server never saw except as the one request that set it. +# +# Needs a server with inbuxa:FrontEnds; until a release has it, pass a build: +# SERVER_BINARY=path/to/inbuxa e2e/vm/run.sh e2e/cases/join.sh +set -uo pipefail + +pass=0; fail=0 +ok() { echo " ok $*"; pass=$((pass+1)); } +bad() { echo " FAIL $*"; fail=$((fail+1)); } + +SERVER_DIR=/var/lib/inbuxa +DIR=/var/lib/inbuxa-joined +SERVER=http://127.0.0.1:8081 +if [ -x /tmp/inbuxa-server-test ]; then + export INBUXA_SERVER_BINARY=/tmp/inbuxa-server-test + # A debug build needs a deeper stack than a release one, as the server's + # own test suites do (RUST_MIN_STACK in its CI). A drop-in made before the + # unit exists applies when it does. + mkdir -p /etc/systemd/system/inbuxa-server.service.d + printf '[Service]\nEnvironment=RUST_MIN_STACK=16777216\n' > /etc/systemd/system/inbuxa-server.service.d/test-build.conf +fi + +rt() { command -v docker >/dev/null 2>&1 && echo docker || echo podman; } +compose() { + if [ "$(rt)" = docker ]; then + docker compose -f "$DIR/compose.yaml" "$@" + else + DOCKER_HOST=unix:///run/podman/podman.sock \ + /usr/local/lib/docker/cli-plugins/docker-compose -f "$DIR/compose.yaml" "$@" + fi +} +jmap() { # jmap TOKEN-or-user:pass CAPABILITY JSON-CALLS + local auth + case "$1" in *:*) auth=(-u "$1") ;; *) auth=(-H "Authorization: Bearer $1") ;; esac + curl -s "${auth[@]}" -H 'Content-Type: application/json' \ + -d "{\"using\":[\"urn:ietf:params:jmap:core\",\"$2\"],\"methodCalls\":$3}" "$SERVER/jmap/" +} +wait_server() { for _ in $(seq 1 60); do [ "$(curl -s -o /dev/null -w '%{http_code}' $SERVER/.well-known/jmap)" != 000 ] && return 0; sleep 2; done; return 1; } + +echo "==> the server, on its own" +OUT="$(/tmp/inbuxa install --local --domain example.test --server host --console skip --webmail skip --yes 2>&1)"; rc=$? +if [ $rc -eq 0 ]; then ok "installed the server alone"; else + bad "server install exit $rc"; echo "$OUT" | tail -15 | sed 's/^/ /' + journalctl -u inbuxa-server -n 30 --no-pager -o cat | sed 's/^/ | /' + echo; echo "==> $pass passed, $fail failed (stopped: no server to join)"; exit 1 +fi +[ -n "${INBUXA_SERVER_BINARY:-}" ] && echo " (server: $(/usr/local/bin/inbuxa-server --version 2>&1 | head -1), from the build given)" + +echo +echo "==> an API key, as an administrator makes one in the console" +# The console is a browser; here the server takes the administrator's +# password for one restart, the way the installer's own setup does. +AUSER=$(awk '/^administrator/ {print $2}' "$SERVER_DIR/credentials.txt") +APASS=$(awk '/^administrator/{getline; print $2}' "$SERVER_DIR/credentials.txt") +echo "INBUXA_HTTP_BASIC_AUTH=all" >> "$SERVER_DIR/server.env" +systemctl restart inbuxa-server; wait_server +EXPIRES=$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ) +ANSWER=$(jmap "$AUSER:$APASS" urn:inbuxa:jmap:registry "[[\"x:ApiKey/set\",{\"create\":{\"k\":{\"description\":\"join test\",\"expiresAt\":\"$EXPIRES\",\"permissions\":{\"@type\":\"Inherit\"}}}},\"0\"]]") +KEY=$(sed -n 's/.*"secret":"\([^"]*\)".*/\1/p' <<<"$ANSWER") +sed -i '/^INBUXA_HTTP_BASIC_AUTH=/d' "$SERVER_DIR/server.env" +systemctl restart inbuxa-server; wait_server +[ -n "$KEY" ] && ok "an API key for the administrator" || { bad "no API key"; head -c 300 <<<"$ANSWER" | sed 's/^/ /'; } + +ACCOUNT=$(curl -s -H "Authorization: Bearer $KEY" $SERVER/jmap/session | grep -o '"primaryAccounts":{[^}]*}' | sed -n 's/^"primaryAccounts":{"[^"]*":"\([^"]*\)".*/\1/p') +[ -n "$ACCOUNT" ] || bad "no account id in the key's session" + +# From here this is "another machine": no install recorded on it. +mv /etc/inbuxa/install.json /etc/inbuxa/install.server.json + +echo +echo "==> what join would do, asking the server first" +OUT="$(INBUXA_JOIN_KEY=wrong-key /tmp/inbuxa join $SERVER --local --dir $DIR --install-deps --dry-run 2>&1)"; rc=$? +[ $rc -ne 0 ] && grep -q "API key" <<<"$OUT" && ok "a wrong key is refused, and says so" || { bad "a wrong key: exit $rc"; echo "$OUT" | tail -5 | sed 's/^/ /'; } +OUT="$(INBUXA_JOIN_KEY=$KEY /tmp/inbuxa join $SERVER --local --dir $DIR --install-deps --dry-run 2>&1)"; rc=$? +[ $rc -eq 0 ] && grep -q "the key works" <<<"$OUT" && ok "the dry run asks the server, and changes nothing" || { bad "dry run exit $rc"; echo "$OUT" | tail -8 | sed 's/^/ /'; } +grep -q "Register these front ends with the server" <<<"$OUT" && ok "and the plan names the registration" || bad "no registration step in the plan" +FE=$(jmap "$KEY" urn:inbuxa:jmap '[["inbuxa:FrontEnds/get",{"accountId":"'"$ACCOUNT"'"},"0"]]') +grep -q '"adminUrl":null' <<<"$FE" && ok "the server still lists no console" || bad "a dry run changed the server: $FE" + +echo +echo "==> joining" +OUT="$(echo "$KEY" | /tmp/inbuxa join $SERVER --key - --local --dir $DIR --install-deps --yes 2>&1)"; rc=$? +echo "$OUT" | grep -v '^ |' | tail -24 | sed 's/^/ /' +[ $rc -eq 0 ] && ok "joined (exit 0)" || bad "exit $rc" +grep -q "$KEY" <<<"$(cat $DIR/* 2>/dev/null)" && bad "the API key was written down here" || ok "the API key was not kept" +STATE="$(compose ps --format '{{.Service}} {{.State}}')" +for s in console webmail; do + grep -q "^$s running" <<<"$STATE" && ok "$s is running" || { bad "$s is not running"; echo "$STATE" | sed 's/^/ /'; } +done +grep -q "^ server:" "$DIR/compose.yaml" && bad "a server was put here too" || ok "no server here" +grep -q '"serverUrl": "http://127.0.0.1:8081"' /etc/inbuxa/install.json && ok "the install record names the server it joined" || bad "no serverUrl in the install record" + +echo +echo "==> the server knows the front ends" +FE=$(jmap "$KEY" urn:inbuxa:jmap '[["inbuxa:FrontEnds/get",{"accountId":"'"$ACCOUNT"'"},"0"]]') +grep -q '"adminUrl":"http://127.0.0.1:8082"' <<<"$FE" && ok "the console's address" || bad "adminUrl: $FE" +grep -q '"webmailUrl":"http://127.0.0.1:8080"' <<<"$FE" && ok "the webmail's address" || bad "webmailUrl: $FE" +grep -q '"webmailClientSecretSet":true' <<<"$FE" && ok "and a webmail secret, which it does not show" || bad "no webmail secret: $FE" +ALLOW=$(curl -s -o /dev/null -D - -X OPTIONS $SERVER/jmap/session -H 'Origin: http://127.0.0.1:8082' \ + -H 'Access-Control-Request-Method: GET' -H 'Access-Control-Request-Headers: authorization' | tr -d '\r' | awk -F': ' 'tolower($1)=="access-control-allow-origin"{print $2}') +[ "$ALLOW" = "http://127.0.0.1:8082" ] && ok "the console's origin may call the server" || bad "access-control-allow-origin: '$ALLOW'" +curl -fsS http://127.0.0.1:8082/ 2>/dev/null | grep -q "content=\"$SERVER\"" && ok "the console points at the server" || bad "the console's api-base-url is not $SERVER" + +echo +echo "==> a person signs in to the joined webmail" +USER=$(awk '/^first mailbox/ {print $3}' "$SERVER_DIR/credentials.txt") +PASS=$(awk '/^first mailbox/{getline; print $2}' "$SERVER_DIR/credentials.txt") +rm -f /tmp/jar +LOC=$(curl -s -o /dev/null -c /tmp/jar -w '%{redirect_url}' "http://127.0.0.1:8080/api/auth/oauth/start?username=$USER&remember=1") +grep -q "^$SERVER/" <<<"$LOC" && ok "the webmail sends sign-in to the server" || bad "sign-in went to '${LOC:-nowhere}'" +q() { sed -n "s/.*[?&]$1=\([^&]*\).*/\1/p" <<<"$LOC"; } +urldecode() { printf '%b' "${1//%/\\x}"; } +STATE=$(q state); CHALLENGE=$(q code_challenge); REDIRECT=$(urldecode "$(q redirect_uri)") +ANSWER=$(curl -s -X POST $SERVER/api/auth -H 'Content-Type: application/json' -H 'Accept: application/json' \ + -d "{\"type\":\"authCode\",\"accountName\":\"$USER\",\"accountSecret\":\"$PASS\",\"clientId\":\"ihasmail-inbuxa\",\"redirectUri\":\"$REDIRECT\",\"codeChallenge\":\"$CHALLENGE\",\"codeChallengeMethod\":\"S256\"}") +AUTHCODE=$(sed -n 's/.*"client_\{0,1\}[cC]ode":"\([^"]*\)".*/\1/p' <<<"$ANSWER") +[ -n "$AUTHCODE" ] && ok "the server takes the joined webmail's redirect" || { bad "the server's sign-in answered"; head -c 200 <<<"$ANSWER" | sed 's/^/ /'; } +BACK=$(curl -s -o /dev/null -b /tmp/jar -c /tmp/jar -w '%{redirect_url}' "$REDIRECT?code=$AUTHCODE&state=$STATE") +grep -q "signin_error" <<<"$BACK" && bad "the webmail's code exchange failed (its secret?): $BACK" || ok "the webmail exchanges the code with the secret made here" +CODE=$(curl -s -o /tmp/login.json -b /tmp/jar -w '%{http_code}' -H 'X-Requested-With: ihasmail' http://127.0.0.1:8080/api/auth/session) +[ "$CODE" = 200 ] && grep -q "urn:ietf:params:jmap:mail" /tmp/login.json && ok "signed in, with mail" || { bad "the session answered $CODE"; head -c 200 /tmp/login.json | sed 's/^/ /'; } + +echo +echo "==> again, and differently" +OUT="$(INBUXA_JOIN_KEY=$KEY /tmp/inbuxa join $SERVER --local --dir $DIR --yes 2>&1)"; rc=$? +[ $rc -eq 0 ] && ok "joining again with the same addresses converges" || { bad "second join exit $rc"; echo "$OUT" | tail -6 | sed 's/^/ /'; } +COUNT=$(compose ps --format '{{.Service}}' | sort -u | wc -l) +[ "$COUNT" = 2 ] && ok "still two containers" || bad "$COUNT containers after a second join" +OUT="$(INBUXA_JOIN_KEY=$KEY /tmp/inbuxa join $SERVER --domain example.test --dir /tmp/elsewhere --dry-run 2>&1)"; rc=$? +[ $rc -ne 0 ] && grep -q -- "--replace" <<<"$OUT" && ok "a console elsewhere is refused without --replace" || { bad "a different console was not refused: exit $rc"; echo "$OUT" | tail -4 | sed 's/^/ /'; } + +mv /etc/inbuxa/install.server.json /etc/inbuxa/install.json.server-kept 2>/dev/null +echo +echo "==> $pass passed, $fail failed" +[ "$fail" -eq 0 ] diff --git a/e2e/vm/run.sh b/e2e/vm/run.sh index 8356518..5f3f8f2 100755 --- a/e2e/vm/run.sh +++ b/e2e/vm/run.sh @@ -39,6 +39,12 @@ fi echo "==> copying it in" vm_scp "$LAB/inbuxa" lab@127.0.0.1:/tmp/inbuxa >/dev/null +# A server build to install instead of the release (INBUXA_SERVER_BINARY in +# the case), for testing a server change before it is released. +if [ -n "${SERVER_BINARY:-}" ]; then + vm_scp "$SERVER_BINARY" lab@127.0.0.1:/tmp/inbuxa-server-test >/dev/null + vm_ssh 'chmod +x /tmp/inbuxa-server-test' +fi [ -z "${OLD_REF:-}" ] || vm_scp "$LAB/inbuxa-old" lab@127.0.0.1:/tmp/inbuxa-old >/dev/null vm_scp "$ROOT/$CASE" lab@127.0.0.1:/tmp/case.sh >/dev/null vm_ssh 'chmod +x /tmp/inbuxa /tmp/case.sh; [ ! -f /tmp/inbuxa-old ] || chmod +x /tmp/inbuxa-old' diff --git a/internal/apply/apply.go b/internal/apply/apply.go index 1eb2d5d..78e831b 100644 --- a/internal/apply/apply.go +++ b/internal/apply/apply.go @@ -680,7 +680,7 @@ func saveState(st *state.State, o plan.Options, f host.Facts, log Log) { } // Verify is the last step: does what was installed actually answer? -func Verify(ctx context.Context, res *Result, stackConsole, stackWebmail bool, log Log) []string { +func Verify(ctx context.Context, res *Result, server, stackConsole, stackWebmail bool, log Log) []string { var problems []string check := func(what, url string, want string) { ctx, cancel := context.WithTimeout(ctx, 10*time.Second) @@ -699,7 +699,9 @@ func Verify(ctx context.Context, res *Result, stackConsole, stackWebmail bool, l } log.Info("%s answers", what) } - check("the mail server", "http://127.0.0.1:8081/.well-known/jmap", "") + if server { + check("the mail server", "http://127.0.0.1:8081/.well-known/jmap", "") + } if stackConsole { check("the console", "http://127.0.0.1:8082/", "api-base-url") } diff --git a/internal/apply/hostserver.go b/internal/apply/hostserver.go index 36f6adc..0624e7e 100644 --- a/internal/apply/hostserver.go +++ b/internal/apply/hostserver.go @@ -81,7 +81,18 @@ func (h hostServer) DataPath() string { return filepath.Join(h.home(), "data") + // Install puts the release binary, the user and the directories in place. It // changes nothing that is already right, so a converge can call it too. func (h hostServer) Install(ctx context.Context) error { - if v := binaryVersion(ctx, HostServerBinary); strings.Contains(v, release.ServerVersion) { + if path := os.Getenv("INBUXA_SERVER_BINARY"); path != "" { + // A server build to test, in place of the release. Said loudly, + // because nothing vouches for it the way the pinned checksum + // vouches for a release. + h.log.Step("installing %s instead of the release, as INBUXA_SERVER_BINARY says (no checksum)", path) + if out, err := exec.CommandContext(ctx, path, "--version").CombinedOutput(); err != nil { + return fmt.Errorf("%s does not run here: %s", path, strings.TrimSpace(string(out))) + } + if err := runQuiet(ctx, "install", "-m", "0755", path, HostServerBinary); err != nil { + return err + } + } else if v := binaryVersion(ctx, HostServerBinary); strings.Contains(v, release.ServerVersion) { h.log.Info("%s is already %s", HostServerBinary, release.ServerVersion) } else { if err := h.fetchBinary(ctx); err != nil { diff --git a/internal/apply/join.go b/internal/apply/join.go new file mode 100644 index 0000000..90da312 --- /dev/null +++ b/internal/apply/join.go @@ -0,0 +1,314 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package apply + +// Join installs the console and the webmail on this machine, for a mail server +// that already runs on another one. +// +// The other machine is never reached except as a browser or a mail client +// would reach it: over its own HTTPS, with an API key its administrator made +// in the console. Through that key the front ends' addresses go into the +// server's inbuxa:FrontEnds, which registers their OAuth clients and puts +// their origins on the cross-origin allowlist, on every node, with no +// restart. Nothing is copied between the machines but that key, and the +// webmail's client secret, which is made here and leaves only inside that +// one request. + +import ( + "context" + "errors" + "fmt" + "net" + "net/http" + "os" + "path/filepath" + "strings" + "time" + + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/compose" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/deps" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/docker" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/jmap" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state" +) + +// JoinCheck is what the server says before anything is installed: that the +// key works, that the server can take front ends this way, and that nothing +// it already lists would be replaced unasked. It changes nothing, so a dry +// run makes it too. +func JoinCheck(ctx context.Context, o plan.Options, key string) error { + srv := &jmap.Client{BaseURL: o.ServerURL, Token: key} + accountID, err := srv.AccountID(ctx) + if err != nil { + var he *jmap.HTTPError + if errors.As(err, &he) && he.Status == http.StatusUnauthorized { + return fmt.Errorf("the server refused the API key; make one in the console under your account's API keys, then pass it with --key") + } + return fmt.Errorf("reaching %s: %w", o.ServerURL, err) + } + fe, err := srv.GetFrontEnds(ctx, accountID) + if err != nil { + return err + } + consoleURL, webmailURL := joinURLs(o) + if o.Shape(plan.Console) != plan.Skip && fe.AdminURL != nil && *fe.AdminURL != consoleURL && !o.Replace { + return fmt.Errorf("the server already lists a console at %s; pass --replace to put this one (%s) in its place", *fe.AdminURL, consoleURL) + } + if o.Shape(plan.Webmail) != plan.Skip { + if fe.EnvironmentWebmailClientSecret { + return fmt.Errorf("the server takes its webmail's client secret from INBUXA_WEBMAIL_CLIENT_SECRET in its environment, " + + "so a webmail elsewhere can't be given one; remove that variable on the server, or join with --webmail skip") + } + if fe.WebmailURL != nil && *fe.WebmailURL != webmailURL && !o.Replace { + return fmt.Errorf("the server already lists a webmail at %s; pass --replace to put this one (%s) in its place", *fe.WebmailURL, webmailURL) + } + } + return nil +} + +// joinURLs are the addresses the front ends here will be reached at. +func joinURLs(o plan.Options) (console, webmail string) { + if o.Local { + return "http://127.0.0.1:8082", "http://127.0.0.1:8080" + } + return "https://" + o.ConsoleHost, "https://" + o.WebmailHost +} + +// Join carries out a join plan. +func Join(ctx context.Context, p plan.Plan, f host.Facts, key string, log Log) (*Result, error) { + o := p.Options + if o.ServerURL == "" { + return nil, errors.New("join needs the server's address") + } + if o.Shape(plan.Server) != plan.Skip { + return nil, errors.New("join installs front ends for a server elsewhere; the server itself is installed with install") + } + for _, c := range []plan.Component{plan.Console, plan.Webmail} { + if o.Shape(c) == plan.Host { + return nil, fmt.Errorf("host installs of the console and the webmail are not built yet: %s was asked for as a host install", c) + } + } + if o.Shape(plan.Console) == plan.Skip && o.Shape(plan.Webmail) == plan.Skip { + return nil, errors.New("nothing to join: both the console and the webmail are skipped") + } + if st, err := state.Load(); err == nil && st.Shapes["server"] != "" { + return nil, fmt.Errorf("this machine runs the mail server itself (a %s install); its front ends are added with install, not join", st.Shapes["server"]) + } + + log.Step("asking the server at %s", o.ServerURL) + if err := JoinCheck(ctx, o, key); err != nil { + return nil, err + } + srv := &jmap.Client{BaseURL: o.ServerURL, Token: key} + accountID, err := srv.AccountID(ctx) + if err != nil { + return nil, err + } + log.Info("the key works, and the server takes front ends over JMAP") + + if len(p.Needs) > 0 && o.InstallDeps { + log.Step("installing what this machine is missing") + if err := deps.Resolve(ctx, log.Out(), p.Needs); err != nil { + return nil, err + } + f = host.Survey(ctx) + } + if !f.Runtime.Usable { + return nil, fmt.Errorf("the front ends run in containers, and containers are not usable here: %s", f.Runtime.Why) + } + + consoleURL, webmailURL := joinURLs(o) + stack := compose.Stack{ + Version: "dev", + Project: "inbuxa", + Domain: o.Domain, + Email: o.ACMEEmail, + Local: o.Local, + ConsoleHost: o.ConsoleHost, + WebmailHost: o.WebmailHost, + Console: o.Shape(plan.Console) == plan.Container, + Webmail: o.Shape(plan.Webmail) == plan.Container, + Proxy: !o.Local && o.Proxy == "caddy", + RemoteServerURL: o.ServerURL, + ServerPublicURL: o.ServerURL, + ConsoleImage: DefaultConsoleImage, + WebmailImage: DefaultWebmailImage, + CaddyImage: DefaultCaddyImage, + ConsoleBind: "127.0.0.1:8082", + WebmailBind: "127.0.0.1:8080", + Subnet: DefaultSubnet, + ACMEDirectory: o.ACMEDirectory, + } + if stack.Console { + stack.ConsoleURL = consoleURL + } + if stack.Webmail { + stack.WebmailURL = webmailURL + } + if o.ACMECARoot != "" { + if err := copyACMERoot(o.ACMECARoot, o.Dir); err != nil { + return nil, err + } + stack.ACMECARoot = "acme-ca-root.pem" + } + + log.Step("writing the deployment into %s", o.Dir) + sec, err := compose.Write(o.Dir, &stack) + if err != nil { + return nil, err + } + log.Info("compose.yaml, .env%s", map[bool]string{true: " and Caddyfile", false: ""}[stack.Proxy]) + + docker.UseRuntime(f.Runtime) + cmp := docker.Compose{Dir: o.Dir, Runtime: f.Runtime} + log.Step("fetching the images") + if err := cmp.Run(ctx, "pull", "--quiet"); err != nil { + return nil, err + } + + log.Step("registering these front ends with the server") + update := map[string]any{} + if stack.Console { + update["adminUrl"] = consoleURL + } + if stack.Webmail { + update["webmailUrl"] = webmailURL + update["webmailClientSecret"] = sec.WebmailOAuth + } + if err := srv.SetFrontEnds(ctx, accountID, update); err != nil { + return nil, fmt.Errorf("inbuxa:FrontEnds: %w", err) + } + for k, v := range update { + if k != "webmailClientSecret" { + log.Info("%s %v", k, v) + } + } + + // Every webmail request reaches the server from one address, this + // machine's, and the server bans per address: exempted, a scanner + // probing the webmail can't take everybody's webmail with it. + if stack.Webmail { + addresses := joinExemptAddresses(ctx, o, stack) + if len(addresses) == 0 { + log.Info("could not tell which address the server sees the webmail at; exempt it with --exempt-address, or in the console under the auto-ban's allowed addresses") + } + for _, addr := range addresses { + err := srv.AllowIP(ctx, addr, "the webmail at "+webmailURL+": every request arrives from this address") + switch { + case err == nil: + log.Info("exempted %s from the auto-ban; the server applies it at its next restart", addr) + case strings.Contains(err.Error(), "primaryKeyViolation"): + // Exempted already: by an earlier join, or by hand + log.Info("%s is already exempted from the auto-ban", addr) + default: + return nil, fmt.Errorf("exempting %s from the auto-ban: %w", addr, err) + } + } + } + + log.Step("starting the front ends") + if err := cmp.Run(ctx, "up", "-d", "--remove-orphans"); err != nil { + return nil, err + } + + st, err := state.Load() + if err == nil { + st.ServerURL = o.ServerURL + saveState(st, o, f, log) + } + + return &Result{ + Dir: o.Dir, + ConsoleURL: stack.ConsoleURL, + WebmailURL: stack.WebmailURL, + ServerURL: o.ServerURL, + }, nil +} + +// joinExemptAddresses is where the server sees the webmail's requests come +// from: what the operator said, loopback for a server on this machine's own +// loopback, or else what the webmail's name resolves to -- the address its +// DNS points at this machine, which is the one it sends from unless +// something in between rewrites it. +func joinExemptAddresses(ctx context.Context, o plan.Options, stack compose.Stack) []string { + if o.ExemptAddress != "" { + return []string{o.ExemptAddress} + } + if stack.WebmailOnHost() { + return []string{"127.0.0.1"} + } + ctx, cancel := context.WithTimeout(ctx, 10*time.Second) + defer cancel() + addrs, err := net.DefaultResolver.LookupHost(ctx, o.WebmailHost) + if err != nil { + return nil + } + return addrs +} + +// JoinVerify is join's last step: the front ends answer here, and the server +// lets the console call it from the browser, which is the part only the +// server can say. +func JoinVerify(ctx context.Context, res *Result, console, webmail bool, log Log) []string { + // Started a moment ago: give them the time to answer at all before + // asking whether they answer correctly. + for _, c := range []struct { + want bool + what string + url string + }{{console, "the console", "http://127.0.0.1:8082/"}, {webmail, "the webmail", "http://127.0.0.1:8080/api/health"}} { + if !c.want { + continue + } + _ = waitFor(ctx, log, c.what+" to start", 60*time.Second, func(ctx context.Context) error { + req, _ := http.NewRequestWithContext(ctx, http.MethodGet, c.url, nil) + resp, err := (&http.Client{Timeout: 5 * time.Second}).Do(req) + if err != nil { + return err + } + resp.Body.Close() + if resp.StatusCode >= 500 { + return fmt.Errorf("answered %s", resp.Status) + } + return nil + }) + } + problems := Verify(ctx, res, false, console, webmail, log) + if console { + ctx, cancel := context.WithTimeout(ctx, 10*time.Second) + defer cancel() + req, _ := http.NewRequestWithContext(ctx, http.MethodOptions, res.ServerURL+"/jmap/session", nil) + origin := strings.TrimRight(res.ConsoleURL, "/") + req.Header.Set("Origin", origin) + req.Header.Set("Access-Control-Request-Method", "GET") + req.Header.Set("Access-Control-Request-Headers", "authorization") + resp, err := (&http.Client{}).Do(req) + switch { + case err != nil: + problems = append(problems, fmt.Sprintf("the server did not answer at %s: %v", res.ServerURL, err)) + case resp.Header.Get("Access-Control-Allow-Origin") != origin: + resp.Body.Close() + problems = append(problems, fmt.Sprintf("the server does not let the console at %s call it yet (no Access-Control-Allow-Origin)", origin)) + default: + resp.Body.Close() + log.Info("the server lets the console call it") + } + } + return problems +} + +// copyACMERoot puts a private ACME CA's root beside the deployment, for +// Caddy: the only thing here that asks for certificates. +func copyACMERoot(path, dir string) error { + root, err := os.ReadFile(path) + if err != nil { + return fmt.Errorf("reading the ACME CA root: %w", err) + } + if err := os.MkdirAll(dir, 0o750); err != nil { + return err + } + return os.WriteFile(filepath.Join(dir, "acme-ca-root.pem"), root, 0o644) +} diff --git a/internal/apply/join_test.go b/internal/apply/join_test.go new file mode 100644 index 0000000..697a851 --- /dev/null +++ b/internal/apply/join_test.go @@ -0,0 +1,120 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package apply + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan" +) + +// fakeServer answers as an inbuxa server would for join: a session for the +// right key, and inbuxa:FrontEnds/get with what frontEnds holds. A nil +// frontEnds is a server too old to have it. +func fakeServer(t *testing.T, frontEnds map[string]any) *httptest.Server { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get("Authorization") != "Bearer good-key" { + w.WriteHeader(http.StatusUnauthorized) + return + } + switch r.URL.Path { + case "/jmap/session": + w.Write([]byte(`{"capabilities":{"urn:ietf:params:jmap:core":{},"urn:inbuxa:jmap":{}}, + "primaryAccounts":{"urn:inbuxa:jmap":"admin1"}}`)) + case "/jmap/": + var req struct { + MethodCalls [][3]json.RawMessage `json:"methodCalls"` + } + json.NewDecoder(r.Body).Decode(&req) + var method string + json.Unmarshal(req.MethodCalls[0][0], &method) + if method != "inbuxa:FrontEnds/get" { + t.Errorf("join's check sent %s", method) + } + if frontEnds == nil { + w.Write([]byte(`{"methodResponses":[["error",{"type":"unknownMethod"},"0"]]}`)) + return + } + b, _ := json.Marshal(map[string]any{"methodResponses": []any{ + []any{"inbuxa:FrontEnds/get", map[string]any{"list": []any{frontEnds}}, "0"}, + }}) + w.Write(b) + default: + w.WriteHeader(http.StatusNotFound) + } + })) + t.Cleanup(srv.Close) + return srv +} + +func joinOptions(serverURL string, replace bool) plan.Options { + return plan.Options{ + ServerURL: serverURL, Domain: "example.com", Replace: replace, + ConsoleHost: "admin.example.com", WebmailHost: "webmail.example.com", + Choices: []plan.Choice{ + {Component: plan.Server, Shape: plan.Skip}, + {Component: plan.Console, Shape: plan.Container}, + {Component: plan.Webmail, Shape: plan.Container}, + }, + } +} + +func TestJoinCheck(t *testing.T) { + ctx := context.Background() + for _, tc := range []struct { + name string + frontEnds map[string]any + key string + replace bool + want string // a word the refusal must contain; "" for none + }{ + {"a fresh server takes them", map[string]any{"environmentWebmailClientSecret": false}, "good-key", false, ""}, + {"the same addresses again", map[string]any{"adminUrl": "https://admin.example.com", "webmailUrl": "https://webmail.example.com"}, "good-key", false, ""}, + {"a wrong key", map[string]any{}, "bad-key", false, "API key"}, + {"a server too old", nil, "good-key", false, "newer than"}, + {"another console listed", map[string]any{"adminUrl": "https://other.example.com"}, "good-key", false, "--replace"}, + {"another console, replaced", map[string]any{"adminUrl": "https://other.example.com"}, "good-key", true, ""}, + {"another webmail listed", map[string]any{"webmailUrl": "https://mail-ui.example.com"}, "good-key", false, "--replace"}, + {"the server's environment holds the secret", map[string]any{"environmentWebmailClientSecret": true}, "good-key", true, "INBUXA_WEBMAIL_CLIENT_SECRET"}, + } { + t.Run(tc.name, func(t *testing.T) { + srv := fakeServer(t, tc.frontEnds) + err := JoinCheck(ctx, joinOptions(srv.URL, tc.replace), tc.key) + switch { + case tc.want == "" && err != nil: + t.Errorf("refused: %v", err) + case tc.want != "" && err == nil: + t.Errorf("accepted, want a refusal naming %q", tc.want) + case tc.want != "" && !strings.Contains(err.Error(), tc.want): + t.Errorf("refusal %q does not name %q", err, tc.want) + } + }) + } +} + +func TestJoinWithoutAWebmailIgnoresItsSecret(t *testing.T) { + srv := fakeServer(t, map[string]any{"environmentWebmailClientSecret": true, "webmailUrl": "https://elsewhere.example.com"}) + o := joinOptions(srv.URL, false) + o.Choices[2].Shape = plan.Skip + if err := JoinCheck(context.Background(), o, "good-key"); err != nil { + t.Errorf("a console-only join was refused over the webmail: %v", err) + } +} + +func TestJoinURLs(t *testing.T) { + o := joinOptions("https://mail.example.com", false) + if c, w := joinURLs(o); c != "https://admin.example.com" || w != "https://webmail.example.com" { + t.Errorf("urls = %s, %s", c, w) + } + o.Local = true + if c, w := joinURLs(o); c != "http://127.0.0.1:8082" || w != "http://127.0.0.1:8080" { + t.Errorf("local urls = %s, %s", c, w) + } +} diff --git a/internal/compose/compose.go b/internal/compose/compose.go index af54ff8..1da96c9 100644 --- a/internal/compose/compose.go +++ b/internal/compose/compose.go @@ -51,6 +51,11 @@ type Stack struct { // only the browser talks to the server from it. HostServer bool + // RemoteServerURL is a mail server on another machine, which the front + // ends here were joined to (`inbuxa join`). Nothing here serves its + // names; the webmail reaches it at this address. + RemoteServerURL string + ServerImage string ConsoleImage string WebmailImage string @@ -145,6 +150,8 @@ func Write(dir string, s *Stack) (Secrets, error) { // arrives from loopback, which is the address the server is told to // exempt from the auto-ban. s.WebmailIP, s.CaddyIP = "127.0.0.1", "127.0.0.1" + } else if s.WebmailOnHost() { + s.WebmailIP = "127.0.0.1" } funcs := template.FuncMap{"join": strings.Join} @@ -215,6 +222,45 @@ func (s Stack) ServerUpstream() string { return s.pick("server:8080", "127.0.0. func (s Stack) WebmailUpstream() string { return s.pick("webmail:8080", "127.0.0.1:8080") } func (s Stack) ConsoleUpstream() string { return s.pick("console:8080", "127.0.0.1:8082") } +// WebmailOnHost is whether the webmail shares the host's network: beside a +// server on the host, or joined to one that is only on this machine's +// loopback, which a container on the project network could not reach. +func (s Stack) WebmailOnHost() bool { + return s.HostServer || (s.RemoteServerURL != "" && isLoopback(s.RemoteServerURL)) +} + +// WebmailServerURL is where the webmail finds the mail server. +func (s Stack) WebmailServerURL() string { + switch { + case s.HostServer: + return "http://127.0.0.1:8081" + case s.RemoteServerURL != "": + return strings.TrimRight(s.RemoteServerURL, "/") + } + return "http://server:8080" +} + +// ServesServer is whether Caddy here serves the mail server's names: not when +// the server is on another machine, whose own proxy does. +func (s Stack) ServesServer() bool { return s.Server || s.HostServer } + +func isLoopback(url string) bool { + host := url + if i := strings.Index(host, "://"); i >= 0 { + host = host[i+3:] + } + host = strings.SplitN(host, "/", 2)[0] + if h, _, err := net.SplitHostPort(host); err == nil { + host = h + } + host = strings.Trim(host, "[]") + if host == "localhost" { + return true + } + ip := net.ParseIP(host) + return ip != nil && ip.IsLoopback() +} + func (s Stack) pick(project, host string) string { if s.HostServer { return host diff --git a/internal/compose/compose_test.go b/internal/compose/compose_test.go index dd1ccac..6eef177 100644 --- a/internal/compose/compose_test.go +++ b/internal/compose/compose_test.go @@ -85,3 +85,37 @@ func TestSecretsSurviveARewrite(t *testing.T) { t.Error("writing the deployment rolled the secrets") } } + +func TestJoinedFrontEndsReachTheServerElsewhere(t *testing.T) { + s := stack(false) + s.Server = false + s.RemoteServerURL = "https://mail.example.com" + c, k := render(t, s) + for _, bad := range []string{"\n server:\n", "depends_on", "network_mode: host", "inbuxa-data:"} { + if strings.Contains(c, bad) { + t.Errorf("compose.yaml has %q", bad) + } + } + if !strings.Contains(c, "MAIL_SERVER_URL: https://mail.example.com") { + t.Errorf("the webmail does not reach the server elsewhere:\n%s", c) + } + if strings.Contains(k, "autoconfig.") || strings.Contains(k, "\nmail.example.com") { + t.Errorf("Caddy here serves the server's names:\n%s", k) + } + if !strings.Contains(k, "reverse_proxy webmail:8080") || !strings.Contains(k, "reverse_proxy console:8080") { + t.Errorf("Caddyfile:\n%s", k) + } +} + +func TestJoinedToALoopbackServerTheWebmailSharesTheHost(t *testing.T) { + s := stack(false) + s.Server, s.Proxy, s.Local = false, false, true + s.RemoteServerURL = "http://127.0.0.1:8081" + c, _ := render(t, s) + if !strings.Contains(c, "network_mode: host") || !strings.Contains(c, "MAIL_SERVER_URL: http://127.0.0.1:8081") { + t.Errorf("compose.yaml:\n%s", c) + } + if s.WebmailIP != "127.0.0.1" { + t.Errorf("the webmail would be exempted at %s", s.WebmailIP) + } +} diff --git a/internal/compose/templates/Caddyfile.tmpl b/internal/compose/templates/Caddyfile.tmpl index 277e0f4..6e98c02 100644 --- a/internal/compose/templates/Caddyfile.tmpl +++ b/internal/compose/templates/Caddyfile.tmpl @@ -40,6 +40,8 @@ } {{- end}} +{{- if .ServesServer}} + # The mail server's web side: JMAP for the front ends and any other client, # CalDAV, CardDAV, autoconfig and MTA-STS. The server is told to believe the # X-Forwarded-For Caddy sets here, so a scanner is banned by its own address @@ -69,3 +71,4 @@ redir https://{host}{uri} 308 } } +{{- end}} diff --git a/internal/compose/templates/compose.yaml.tmpl b/internal/compose/templates/compose.yaml.tmpl index a925a36..4e36399 100644 --- a/internal/compose/templates/compose.yaml.tmpl +++ b/internal/compose/templates/compose.yaml.tmpl @@ -4,7 +4,11 @@ # from this directory. Secrets are in .env beside it and the administrator's # password is in credentials.txt -- both readable only by root. # -{{- if .HostServer}} +{{- if .RemoteServerURL}} +# The mail server is on another machine, {{.RemoteServerURL}}; these front +# ends were joined to it with `inbuxa join`, which registered their addresses +# with it. Nothing here holds mail. +{{- else if .HostServer}} # The mail server runs on this machine under systemd (inbuxa-server.service), # not in this project. Its plain HTTP is on loopback only, which is why the # webmail and Caddy share the host's network: that is where they reach it, as @@ -91,21 +95,20 @@ services: # signs everyone out; nothing else is lost, because nothing else is kept. read_only: true tmpfs: [/tmp] -{{- if .HostServer}} - # On the host's network, listening on loopback only, beside the server. +{{- if .WebmailOnHost}} + # On the host's network, listening on loopback only, where it reaches + # the server. network_mode: host {{- else}} ports: - "{{.WebmailBind}}:8080" {{- end}} environment: -{{- if .HostServer}} +{{- if .WebmailOnHost}} HOST: 127.0.0.1 PORT: "8080" - MAIL_SERVER_URL: http://127.0.0.1:8081 -{{- else}} - MAIL_SERVER_URL: http://server:8080 {{- end}} + MAIL_SERVER_URL: {{.WebmailServerURL}} APP_SECRET: ${APP_SECRET:?APP_SECRET is missing from .env} APP_NAME: inbuxa IMMUTABLE: "1" @@ -130,7 +133,7 @@ services: # is not the webmail. PUSH_URL: {{.WebmailURL}} {{- end}} -{{- if not .HostServer}} +{{- if not .WebmailOnHost}} networks: stack: ipv4_address: {{.WebmailIP}} @@ -167,7 +170,7 @@ services: ipv4_address: {{.CaddyIP}} {{- end}} {{- end}} -{{- if or .Server .Console}} +{{- if or .Server .Console (and .Webmail (not .WebmailOnHost)) (and .Proxy (not .HostServer))}} networks: stack: diff --git a/internal/jmap/client.go b/internal/jmap/client.go index ecabb00..1f90857 100644 --- a/internal/jmap/client.go +++ b/internal/jmap/client.go @@ -89,6 +89,10 @@ func (c *Client) httpClient() *http.Client { // before it -- JMAP stops nothing on an error, but every caller here needs // all of its calls to have worked. func (c *Client) Do(ctx context.Context, calls ...Call) ([]Response, error) { + return c.do(ctx, using, calls...) +} + +func (c *Client) do(ctx context.Context, using []string, calls ...Call) ([]Response, error) { mc := make([][3]any, len(calls)) for i, call := range calls { mc[i] = [3]any{call.Method, call.Args, call.ID} diff --git a/internal/jmap/frontends.go b/internal/jmap/frontends.go new file mode 100644 index 0000000..498e3ff --- /dev/null +++ b/internal/jmap/frontends.go @@ -0,0 +1,111 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package jmap + +// inbuxa:FrontEnds (contract C-4): where a server's console and webmail are. +// Setting it registers their OAuth clients and allows their origins on every +// node, which is all a front end on another machine needs from the server -- +// and why `inbuxa join` needs nothing from that machine but an API key. + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" +) + +var usingInbuxa = []string{"urn:ietf:params:jmap:core", "urn:inbuxa:jmap"} + +// FrontEnds is the server's record of its front ends, and what its +// environment says beside it. +type FrontEnds struct { + AdminURL *string `json:"adminUrl"` + WebmailURL *string `json:"webmailUrl"` + WebmailClientSecretSet bool `json:"webmailClientSecretSet"` + ExtraOrigins []string `json:"extraOrigins"` + EnvironmentAdminURL *string `json:"environmentAdminUrl"` + EnvironmentWebmailURL *string `json:"environmentWebmailUrl"` + EnvironmentWebmailClientSecret bool `json:"environmentWebmailClientSecret"` +} + +// ErrNoFrontEnds is a server too old to have inbuxa:FrontEnds. +var ErrNoFrontEnds = errors.New("this server has no inbuxa:FrontEnds; it needs a release newer than 2026.10.10.1") + +// AccountID is the signed-in account's id, which inbuxa: methods name. +func (c *Client) AccountID(ctx context.Context) (string, error) { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.BaseURL+"/jmap/session", nil) + if err != nil { + return "", err + } + if c.Token != "" { + req.Header.Set("Authorization", "Bearer "+c.Token) + } else { + req.SetBasicAuth(c.Username, c.Password) + } + res, err := c.httpClient().Do(req) + if err != nil { + return "", err + } + defer res.Body.Close() + if res.StatusCode != http.StatusOK { + return "", &HTTPError{Status: res.StatusCode, Body: http.StatusText(res.StatusCode)} + } + var session struct { + Capabilities map[string]json.RawMessage `json:"capabilities"` + PrimaryAccounts map[string]string `json:"primaryAccounts"` + } + if err := json.NewDecoder(res.Body).Decode(&session); err != nil { + return "", fmt.Errorf("not a JMAP session: %w", err) + } + if _, ok := session.Capabilities["urn:inbuxa:jmap"]; !ok { + return "", errors.New("this is not an inbuxa server: its session has no urn:inbuxa:jmap") + } + for _, capability := range []string{"urn:inbuxa:jmap", "urn:ietf:params:jmap:core"} { + if id := session.PrimaryAccounts[capability]; id != "" { + return id, nil + } + } + for _, id := range session.PrimaryAccounts { + return id, nil + } + return "", errors.New("the session names no account") +} + +// GetFrontEnds reads inbuxa:FrontEnds. +func (c *Client) GetFrontEnds(ctx context.Context, accountID string) (FrontEnds, error) { + var fe FrontEnds + rs, err := c.do(ctx, usingInbuxa, Call{"inbuxa:FrontEnds/get", map[string]any{"accountId": accountID}, "0"}) + var me *MethodError + if errors.As(err, &me) && me.Type == "unknownMethod" { + return fe, ErrNoFrontEnds + } + if err != nil { + return fe, err + } + var got struct { + List []FrontEnds `json:"list"` + } + if err := json.Unmarshal(rs[0].Args, &got); err != nil { + return fe, err + } + if len(got.List) != 1 { + return fe, errors.New("inbuxa:FrontEnds/get returned nothing: is this account a server administrator?") + } + return got.List[0], nil +} + +// SetFrontEnds updates inbuxa:FrontEnds with the properties given; null +// clears one. +func (c *Client) SetFrontEnds(ctx context.Context, accountID string, update map[string]any) error { + rs, err := c.do(ctx, usingInbuxa, Call{"inbuxa:FrontEnds/set", map[string]any{ + "accountId": accountID, + "update": map[string]any{"singleton": update}, + }, "0"}) + if err != nil { + return err + } + _, err = DecodeSet(rs[0]) + return err +} diff --git a/internal/plan/plan.go b/internal/plan/plan.go index 643c2c9..b6e9552 100644 --- a/internal/plan/plan.go +++ b/internal/plan/plan.go @@ -70,6 +70,16 @@ type Options struct { ACMEDirectory string ACMECARoot string + // ServerURL is a mail server on another machine that the front ends here + // are joined to (`inbuxa join`); empty when the server is installed here. + ServerURL string + // Replace lets join put its front ends in place of others the server + // already lists. + Replace bool + // ExemptAddress is the address the server sees the webmail's requests + // come from, when it is not what the webmail's name resolves to. + ExemptAddress string + // Where this came from, when it came from a topology file: the machine's // name in it, and the path, both recorded in the state file so a later // run knows which part of which file this machine is. @@ -391,6 +401,19 @@ func Build(f host.Facts, o Options) (Plan, error) { } } + if o.ServerURL != "" { + detail := []string{"the server at " + o.ServerURL + ", with the API key given"} + if o.Shape(Console) != Skip { + detail = append(detail, "the console's address, which registers its OAuth client and allows its origin") + } + if o.Shape(Webmail) != Skip { + detail = append(detail, + "the webmail's address and a client secret generated here, kept in "+o.Dir+"/.env", + "this machine's address exempted from the server's auto-ban, as every webmail request comes from it") + } + p.Steps = append(p.Steps, Step{Title: "Register these front ends with the server (inbuxa:FrontEnds)", Detail: detail}) + } + p.Steps = append(p.Steps, Step{ Title: "Check it works", Detail: []string{ @@ -515,6 +538,9 @@ func describe(o Options) string { if o.Local { where = "a loopback evaluation" } + if o.ServerURL != "" { + where += ", joined to " + o.ServerURL + } return strings.Join(parts, ", ") + " -- " + where } diff --git a/internal/state/state.go b/internal/state/state.go index 56d44b4..6b3720b 100644 --- a/internal/state/state.go +++ b/internal/state/state.go @@ -32,6 +32,7 @@ type State struct { Domain string `json:"domain,omitempty"` // Shapes map[string]string `json:"shapes"` // component -> container|host Topology string `json:"topology,omitempty"` // the file this came from, if any + ServerURL string `json:"serverUrl,omitempty"` // the server on another machine these front ends were joined to Updated time.Time `json:"updated"` // Installer string `json:"installer,omitempty"` // the version that wrote this } -- 2.54.0