inbuxa join: the console and the webmail here, for a server elsewhere #16

Merged
jcoffey-dev merged 1 commits from feat/join into main 2026-10-12 13:23:22 +00:00
16 changed files with 1010 additions and 14 deletions

No files matched your search

+20 -1
View File
@@ -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=<commit> 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
+149 -1
View File
@@ -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{}
+148
View File
@@ -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 ]
+6
View File
@@ -39,6 +39,12 @@ fi
echo "==> copying it in"
vm_scp "$LAB/inbuxa" [email protected]:/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" [email protected]:/tmp/inbuxa-server-test >/dev/null
vm_ssh 'chmod +x /tmp/inbuxa-server-test'
fi
[ -z "${OLD_REF:-}" ] || vm_scp "$LAB/inbuxa-old" [email protected]:/tmp/inbuxa-old >/dev/null
vm_scp "$ROOT/$CASE" [email protected]:/tmp/case.sh >/dev/null
vm_ssh 'chmod +x /tmp/inbuxa /tmp/case.sh; [ ! -f /tmp/inbuxa-old ] || chmod +x /tmp/inbuxa-old'
+4 -2
View File
@@ -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")
}
+12 -1
View File
@@ -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 {
+314
View File
@@ -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)
}
+120
View File
@@ -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)
}
}
+46
View File
@@ -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
+34
View File
@@ -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)
}
}
@@ -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}}
+12 -9
View File
@@ -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:
+4
View File
@@ -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}
+111
View File
@@ -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
}
+26
View File
@@ -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
}
+1
View File
@@ -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
}