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 }