Files
inbuxa-installer/internal/jmap/setup.go
T
jcoffey-dev bef9f459a6
ci / test (pull_request) Successful in 1m37s
Move the server between a container and the host
`install` run again with the other --server now moves the mail server,
with its configuration and mail, instead of refusing ("not built yet").

- Needs an API key (--key - / INBUXA_API_KEY, never written down), as
  certs and join do: the server's listeners (jmap.HostListeners, and the
  new ContainerListeners) and its auto-ban exemptions change with the
  shape, and only the server changes those.
- beginMove checks the key, stops what runs here and archives the data
  into <dir>/backups before anything of the new shape is written; finish
  copies it (renamed into place, or streamed into the volumes), rewrites
  the one path config.json names, starts the server in its new shape --
  on the host first behind the loopback fence (modeFenced) until its
  listeners are fitted -- and checks it came back configured.
- Copied, never moved: the volumes, or <dir>/server, stay where they were.
  Leftovers of an earlier install in the target are archived and emptied,
  never mixed in. A failure in finish, or anything stopping the run
  before it (abort), puts the old shape back.
- The plan says when a run is a move. `apply -f` moves too.

e2e/cases/move-server.sh: 56/56 (no key and a wrong key change nothing;
a broken host binary puts the container back; container -> host -> container
keeping an account and IMAP sign-in, front ends answering, status agreeing).
install-host.sh expects the key refusal in place of "not built yet": 44/44;
uninstall-host 14/14, rerun-host-server 12/12.
2026-10-14 20:32:41 -07:00

499 lines
17 KiB
Go

// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
package jmap
// This file drives an inbuxa server's first boot over JMAP: bootstrap,
// certificates, the proxy's address, and the first account. It came from
// the webmail-oneshot and keeps its sequence, which SPEC.md 6.2 describes.
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"time"
)
// Admin is the permanent administrator bootstrap provisions.
type Admin struct {
Username string `json:"username"`
Secret string `json:"secret"`
}
// CheckBootstrapMode confirms the server is fresh. x:Bootstrap exists only in
// bootstrap mode, so a server that has been set up before -- a volume left
// over from an earlier run, say -- refuses the call, and the tool stops before
// writing anything into someone's configured mail server.
func (c *Client) CheckBootstrapMode(ctx context.Context) error {
_, err := c.Do(ctx, Call{"x:Bootstrap/get", map[string]any{"ids": []string{"singleton"}, "properties": []string{"id"}}, "0"})
var me *MethodError
var he *HTTPError
// A configured server either refuses the method or, having no bootstrap
// account any more, the credentials.
if errors.As(err, &me) || (errors.As(err, &he) && he.Status == 401) {
return fmt.Errorf("this server is not in bootstrap mode, so it has been configured before (%w)", err)
}
return err
}
// Bootstrap completes the setup wizard the web UI would otherwise walk someone
// through, and returns the administrator it creates. The temporary bootstrap
// account stops working once the server restarts out of bootstrap mode.
//
// dataPath is where the built-in store keeps its files. Empty leaves the
// server's default, /var/lib/inbuxa/, which is the image's data volume; a
// server on the host is given a directory of its own, so its store does not
// share a directory with the deployment's files.
func (c *Client) Bootstrap(ctx context.Context, hostname, domain, dataPath string) (Admin, error) {
update := map[string]any{
"serverHostname": hostname,
"defaultDomain": domain,
// Off, and done explicitly afterwards (see EnableACME): on 0.16.22 this
// flag creates no ACME provider and leaves the domain on manual
// certificates, so turning it on would only look like it had worked.
"requestTlsCertificate": false,
"generateDkimKeys": true,
// The default logs to /var/log/stalwart, which does not exist in the
// image and is not a volume. A container logs to stdout.
"tracer": map[string]any{
"@type": "Stdout", "enable": true, "level": "info",
"ansi": false, "multiline": false, "lossy": false,
"events": map[string]any{}, "eventsPolicy": "exclude",
},
}
if dataPath != "" {
update["dataStore"] = map[string]any{"@type": "RocksDb", "path": dataPath}
}
rs, err := c.Do(ctx, Call{"x:Bootstrap/set", map[string]any{"update": map[string]any{"singleton": update}}, "0"})
if err != nil {
return Admin{}, err
}
s, err := DecodeSet(rs[0])
if err != nil {
return Admin{}, err
}
var a Admin
if err := json.Unmarshal(s.Updated["singleton"], &a); err != nil || a.Username == "" || a.Secret == "" {
return Admin{}, errors.New("x:Bootstrap/set did not return the administrator it created")
}
return a, nil
}
// CreateAPIKey gives the signed-in account an API key and returns its id and
// the token, which the server shows only once. It expires on its own after
// ttl, so a setup that stops halfway does not leave a working key behind.
func (c *Client) CreateAPIKey(ctx context.Context, description string, ttl time.Duration) (id, token string, err error) {
args := map[string]any{"create": map[string]any{
"key": map[string]any{
"description": description,
"expiresAt": time.Now().UTC().Add(ttl).Format(time.RFC3339),
"permissions": map[string]any{"@type": "Inherit"},
},
}}
rs, err := c.Do(ctx, Call{"x:ApiKey/set", args, "0"})
if err != nil {
return "", "", err
}
s, err := DecodeSet(rs[0])
if err != nil {
return "", "", err
}
var key struct {
ID string `json:"id"`
Secret string `json:"secret"`
}
if err := json.Unmarshal(s.Created["key"], &key); err != nil || key.ID == "" || key.Secret == "" {
return "", "", errors.New("x:ApiKey/set did not return the key it created")
}
return key.ID, key.Secret, nil
}
// DestroyAPIKey removes an API key from the signed-in account.
func (c *Client) DestroyAPIKey(ctx context.Context, id string) error {
rs, err := c.Do(ctx, Call{"x:ApiKey/set", map[string]any{"destroy": []string{id}}, "0"})
if err != nil {
return err
}
_, err = DecodeSet(rs[0])
return err
}
// DomainID finds a domain by name.
func (c *Client) DomainID(ctx context.Context, name string) (string, error) {
rs, err := c.Do(ctx,
Call{"x:Domain/query", map[string]any{}, "0"},
Call{"x:Domain/get", map[string]any{
"#ids": map[string]any{"resultOf": "0", "name": "x:Domain/query", "path": "/ids"},
"properties": []string{"name"},
}, "1"},
)
if err != nil {
return "", err
}
var got struct {
List []struct{ ID, Name string } `json:"list"`
}
if err := json.Unmarshal(rs[1].Args, &got); err != nil {
return "", err
}
for _, d := range got.List {
if d.Name == name {
return d.ID, nil
}
}
return "", fmt.Errorf("domain %s does not exist on this server", name)
}
// EnableACME creates an ACME account using HTTP-01 and moves the domain's
// certificates onto it. the server starts the order at once, with no restart.
//
// HTTP-01 rather than the server's default TLS-ALPN-01, because Caddy holds 443.
// Caddy forwards /.well-known/acme-challenge/ on port 80 for the server's names
// to the server and uses TLS-ALPN-01 itself, so the two never compete.
func (c *Client) EnableACME(ctx context.Context, domainID, directory, contact string) (string, error) {
provider := map[string]any{
"challengeType": "Http01",
"contact": map[string]bool{contact: true},
"renewBefore": "R23",
"maxRetries": 10,
"reuseKey": false,
}
if directory != "" {
provider["directory"] = directory
}
rs, err := c.Do(ctx,
Call{"x:AcmeProvider/set", map[string]any{"create": map[string]any{"acme": provider}}, "0"},
Call{"x:Domain/set", map[string]any{"update": map[string]any{domainID: automaticCertificates("#acme")}}, "1"},
)
if err != nil {
return "", err
}
s, err := DecodeSet(rs[0])
if err != nil {
return "", err
}
id, err := CreatedID(s, "acme")
if err != nil {
return "", fmt.Errorf("x:AcmeProvider/set: %w", err)
}
if _, err := DecodeSet(rs[1]); err != nil {
return id, err
}
return id, nil
}
// CertificateManagement says how the domain's certificates are managed:
// "Automatic" with the ACME provider's id, or "Manual" with none.
func (c *Client) CertificateManagement(ctx context.Context, domainID string) (kind, providerID string, err error) {
var got struct {
List []struct {
CertificateManagement struct {
Type string `json:"@type"`
AcmeProviderID string `json:"acmeProviderId"`
} `json:"certificateManagement"`
} `json:"list"`
}
rs, err := c.Do(ctx, Call{"x:Domain/get", map[string]any{"ids": []string{domainID}, "properties": []string{"certificateManagement"}}, "0"})
if err != nil {
return "", "", err
}
if err := json.Unmarshal(rs[0].Args, &got); err != nil || len(got.List) != 1 {
return "", "", errors.New("x:Domain/get did not return the domain")
}
cm := got.List[0].CertificateManagement
return cm.Type, cm.AcmeProviderID, nil
}
// RetryCertificates starts a fresh ACME order for the domain. A failed order
// is not retried on a restart; moving the domain to manual and straight back
// is what starts a new one.
func (c *Client) RetryCertificates(ctx context.Context, domainID string) error {
kind, providerID, err := c.CertificateManagement(ctx, domainID)
if err != nil {
return err
}
if kind != "Automatic" || providerID == "" {
return fmt.Errorf("the domain's certificates are %q, not managed by ACME", kind)
}
rs, err := c.Do(ctx,
Call{"x:Domain/set", map[string]any{"update": map[string]any{domainID: map[string]any{"certificateManagement": map[string]any{"@type": "Manual"}}}}, "0"},
Call{"x:Domain/set", map[string]any{"update": map[string]any{domainID: automaticCertificates(providerID)}}, "1"},
)
if err != nil {
return err
}
for _, r := range rs {
if _, err := DecodeSet(r); err != nil {
return err
}
}
return nil
}
func automaticCertificates(providerID string) map[string]any {
return map[string]any{"certificateManagement": map[string]any{
"@type": "Automatic",
"acmeProviderId": providerID,
// Empty is the server's default set: the mail host plus autoconfig,
// autodiscover, mta-sts and ua-auto-config under the domain.
"subjectAlternativeNames": map[string]bool{},
}}
}
// Certificate is what the tool reports about an issued certificate.
type Certificate struct {
Issuer string `json:"issuer"`
NotValidAfter string `json:"notValidAfter"`
SubjectAlternativeNames map[string]bool `json:"subjectAlternativeNames"`
}
// Certificates lists the certificates the server holds.
func (c *Client) Certificates(ctx context.Context) ([]Certificate, error) {
rs, err := c.Do(ctx,
Call{"x:Certificate/query", map[string]any{}, "0"},
Call{"x:Certificate/get", map[string]any{
"#ids": map[string]any{"resultOf": "0", "name": "x:Certificate/query", "path": "/ids"},
"properties": []string{"issuer", "notValidAfter", "subjectAlternativeNames"},
}, "1"},
)
if err != nil {
return nil, err
}
var got struct {
List []Certificate `json:"list"`
}
return got.List, json.Unmarshal(rs[1].Args, &got)
}
// TrustForwardedFor makes the server take a client's address from
// X-Forwarded-For. Its auto-ban works per address: behind Caddy, without this,
// one scanner probing for WordPress bans Caddy -- and with it every autoconfig
// lookup, DAV client and certificate renewal that comes through it. Seen on
// 0.16.22, as was the fix. It applies only once the server restarts.
//
// Safe here because nothing untrusted reaches the server's HTTP port: it is
// published on loopback only, and on the private network the only peers are
// Caddy, which sets the header itself, and the webmail, which sends none.
func (c *Client) TrustForwardedFor(ctx context.Context) error {
rs, err := c.Do(ctx, Call{"x:Http/set", map[string]any{"update": map[string]any{"singleton": map[string]any{"useXForwarded": true}}}, "0"})
if err != nil {
return err
}
_, err = DecodeSet(rs[0])
return err
}
// AllowIP exempts an address from the auto-ban. It applies only once the server
// restarts.
func (c *Client) AllowIP(ctx context.Context, address, reason string) error {
rs, err := c.Do(ctx, Call{"x:AllowedIp/set", map[string]any{"create": map[string]any{
"allow": map[string]any{"address": address, "reason": reason},
}}, "0"})
if err != nil {
return err
}
s, err := DecodeSet(rs[0])
if err != nil {
return err
}
_, err = CreatedID(s, "allow")
return err
}
// CreateUser creates an ordinary mailbox, in the shape the webmail's own
// Administration creates one.
func (c *Client) CreateUser(ctx context.Context, name, domainID, password string) (string, error) {
rs, err := c.Do(ctx, Call{"x:Account/set", map[string]any{"create": map[string]any{
"user": map[string]any{
"@type": "User",
"name": name,
"domainId": domainID,
"description": nil,
"credentials": map[string]any{"0": map[string]any{"@type": "Password", "secret": password}},
"roles": map[string]any{"@type": "User"},
"permissions": map[string]any{"@type": "Inherit"},
"quotas": map[string]any{},
"aliases": map[string]any{},
"memberGroupIds": map[string]any{},
// Required on create. Turning it on cannot be undone, which is not a
// decision for a deploy tool to make on anyone's behalf.
"encryptionAtRest": map[string]any{"@type": "Disabled"},
},
}}, "0"})
if err != nil {
return "", err
}
s, err := DecodeSet(rs[0])
if err != nil {
return "", err
}
return CreatedID(s, "user")
}
// DNSZone returns the records the server wants published for the domain, as a
// zone file fragment: MX, SPF, DKIM, DMARC, the SRV records, MTA-STS and the
// autoconfig names. It has no A or AAAA records; those depend on the host.
func (c *Client) DNSZone(ctx context.Context, domainID string) (string, error) {
rs, err := c.Do(ctx, Call{"x:Domain/get", map[string]any{"ids": []string{domainID}, "properties": []string{"dnsZoneFile"}}, "0"})
if err != nil {
return "", err
}
var got struct {
List []struct {
DNSZoneFile string `json:"dnsZoneFile"`
} `json:"list"`
}
if err := json.Unmarshal(rs[0].Args, &got); err != nil || len(got.List) != 1 {
return "", errors.New("x:Domain/get did not return the domain")
}
return got.List[0].DNSZoneFile, nil
}
// Listener is one of the server's network listeners, as much of it as
// HostListeners needs to tell them apart.
type Listener struct {
ID string `json:"id"`
Name string `json:"name"`
Protocol string `json:"protocol"`
TLSImplicit bool `json:"tlsImplicit"`
Bind map[string]bool `json:"bind"`
}
// Listeners lists the server's network listeners.
func (c *Client) Listeners(ctx context.Context) ([]Listener, error) {
rs, err := c.Do(ctx,
Call{"x:NetworkListener/query", map[string]any{}, "0"},
Call{"x:NetworkListener/get", map[string]any{
"#ids": map[string]any{"resultOf": "0", "name": "x:NetworkListener/query", "path": "/ids"},
"properties": []string{"name", "protocol", "tlsImplicit", "bind"},
}, "1"},
)
if err != nil {
return nil, err
}
var got struct {
List []Listener `json:"list"`
}
return got.List, json.Unmarshal(rs[1].Args, &got)
}
// ContainerListeners undoes HostListeners, for a server moving from the host
// into a container: every listener back on [::], plain HTTP on 8080, which
// is what the compose file publishes. The HTTPS listener HostListeners took
// away is not put back: the proxy terminates TLS in front of a container as
// well, and the container's 443 is not published. Like any listener change
// it takes effect when the server next starts.
func (c *Client) ContainerListeners(ctx context.Context) error {
ls, err := c.Listeners(ctx)
if err != nil {
return err
}
update := map[string]any{}
for _, l := range ls {
binds := map[string]bool{}
for addr := range l.Bind {
if i := strings.LastIndex(addr, ":"); i >= 0 {
binds["[::]"+addr[i:]] = true
}
}
if l.Protocol == "http" && !l.TLSImplicit {
binds = map[string]bool{"[::]:8080": true}
}
update[l.ID] = map[string]any{"bind": binds}
}
if len(update) == 0 {
return nil
}
rs, err := c.Do(ctx, Call{"x:NetworkListener/set", map[string]any{"update": update}, "0"})
if err != nil {
return err
}
_, err = DecodeSet(rs[0])
return err
}
// AllowedIPs is the set of addresses already exempted from the auto-ban.
func (c *Client) AllowedIPs(ctx context.Context) (map[string]bool, error) {
rs, err := c.Do(ctx,
Call{"x:AllowedIp/query", map[string]any{}, "0"},
Call{"x:AllowedIp/get", map[string]any{
"#ids": map[string]any{"resultOf": "0", "name": "x:AllowedIp/query", "path": "/ids"},
"properties": []string{"address"},
}, "1"},
)
if err != nil {
return nil, err
}
var got struct {
List []struct {
Address string `json:"address"`
} `json:"list"`
}
if err := json.Unmarshal(rs[1].Args, &got); err != nil {
return nil, err
}
have := map[string]bool{}
for _, a := range got.List {
have[a.Address] = true
}
return have, nil
}
// HostListeners fits the listeners a server creates on its first configured
// start to a server running on the host rather than in a container.
//
// In a container they are all on [::] inside the container, and only what
// the compose file publishes is reachable. On the host there is nothing in
// between, so the defaults would put plain HTTP on every interface at 8080,
// where the webmail listens, and take 443, which belongs to the proxy. So:
//
// - plain HTTP moves to httpBind, on loopback, where the proxy and the
// webmail reach it -- the same place a container install publishes it;
// - the server's own HTTPS listener goes: the proxy terminates TLS for the
// server's names, as it does in front of a container;
// - with local, every other listener moves to loopback too, since a
// loopback evaluation publishes nothing.
//
// It takes effect at the next restart.
func (c *Client) HostListeners(ctx context.Context, httpBind string, local bool) error {
ls, err := c.Listeners(ctx)
if err != nil {
return err
}
update, destroy := map[string]any{}, []string{}
for _, l := range ls {
switch {
case l.Protocol == "http" && l.TLSImplicit:
destroy = append(destroy, l.ID)
case l.Protocol == "http":
update[l.ID] = map[string]any{"bind": map[string]bool{httpBind: true}}
case local:
binds := map[string]bool{}
for addr := range l.Bind {
if i := strings.LastIndex(addr, ":"); i >= 0 {
binds["127.0.0.1"+addr[i:]] = true
}
}
update[l.ID] = map[string]any{"bind": binds}
}
}
if len(update) == 0 && len(destroy) == 0 {
return nil
}
args := map[string]any{}
if len(update) > 0 {
args["update"] = update
}
if len(destroy) > 0 {
args["destroy"] = destroy
}
rs, err := c.Do(ctx, Call{"x:NetworkListener/set", args, "0"})
if err != nil {
return err
}
_, err = DecodeSet(rs[0])
return err
}