Fix three defects a full VM migration exposed

Ran a complete 0.15.5 -> 0.16.14 migration of the smoke VM, driving the
phases in the order the real pipeline will. It worked - all mail intact and
readable afterwards, all ten listeners up, cutover executed for the first
time ever and checkpoint resume exercised - and it exposed three defects.

1. The converted config was installed root-owned while the service runs as
   its own user. Stalwart crash-looped 28 times on "Failed to read data
   store settings: Permission denied", minutes after the mistake and
   nowhere near it. This is the same ownership trap that retired the
   rollback implementation, in a new place: writing files as root is the
   natural thing for a tool running as root to do, and it is wrong every
   time the service is not root.

   Cutover now installs the config itself, copying ownership and mode from
   the config being replaced.

2. v0.16.14 does not serve /api - the endpoint stalwartapi assumed.
   Confirmed against a fully migrated, fully configured, serving instance
   rather than a sandbox: /api, /api/principal and /jmap/ all 404. The JMAP
   endpoint is the one the session document advertises, which is what RFC
   8620 discovery is for.

   The client now discovers it, re-basing the advertised path onto the
   operator's host: a real instance advertises its canonical public URL
   ("https://mail.smoke.test/jmap/") which frequently isn't reachable from
   where this tool runs. The session is authoritative about the path; the
   operator is authoritative about the host.

3. Dispatching on the urn:stalwart:jmap capability was wrong, because
   NEITHER version advertises it - not 0.15.5, and not a fully migrated
   0.16.14. That sent 0.16 instances down the 0.15 REST path where every
   call 404s. The client probes what the instance actually serves instead.
   Less elegant than a declared capability, with the advantage of being
   true.

Also: a JMAP "forbidden" now explains itself. An account holding the admin
role before the migration was refused x:Account/query afterwards, and a
bare "forbidden" gives an operator nowhere to start. Whether the role
failed to carry or v0.16 wants different permissions was not isolated, and
that question is recorded as open - it gates quota recalculation and any
post-migration validation.

Verified against both live instances: the 0.15.5 reports 3 accounts and its
domain over REST, and the migrated 0.16.14 routes to JMAP, finds the right
endpoint, and returns the explained refusal.

internal/stalwartapi/management.go

@@ -39,12 +39,16 @@ type methodResponse struct {
 	CallID string
 }
 
-// call POSTs one JMAP-style request to the management API (Stalwart's /api
-// endpoint - see docs/ref/object/account.md, which is distinct from /jmap)
-// using this Client's own credentials, and returns its parsed method
-// responses in order.
+// call POSTs one JMAP-style request to the management API using this
+// Client's own credentials, and returns its parsed method responses in
+// order. The endpoint is discovered from the instance's session document -
+// see apiEndpoint for why it is not simply BaseURL + "/api".
 func (c *Client) call(ctx context.Context, using []string, methodCalls []any) ([]methodResponse, error) {
-	return c.callAs(ctx, c.Username, c.Password, strings.TrimRight(c.BaseURL, "/")+"/api", using, methodCalls)
+	endpoint, err := c.apiEndpoint(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return c.callAs(ctx, c.Username, c.Password, endpoint, using, methodCalls)
 }
 
 // callAs is call's underlying primitive: it accepts an explicit
@@ -128,14 +132,12 @@ type account struct {
 // exactly what's missing rather than silently treating an unreachable
 // account's mailboxes as having zero messages.
 func (c *Client) AccountSnapshot(ctx context.Context) (*Snapshot, error) {
-	isJMAP, err := c.hasJMAPManagement(ctx)
+	isREST, err := c.hasRESTManagement(ctx)
 	if err != nil {
 		return nil, fmt.Errorf("stalwartapi: discover which management API this instance speaks: %w", err)
 	}
-	if !isJMAP {
-		// No urn:stalwart:jmap: this is a 0.15.x instance, whose
-		// management API is REST. Confirmed against a live 0.15.5 server -
-		// see principal.go.
+	if isREST {
+		// v0.15.x: REST at /api/principal. See principal.go.
 		return c.principalSnapshotREST(ctx)
 	}
 	return c.accountSnapshotJMAP(ctx)
@@ -205,13 +207,43 @@ func (c *Client) accountSnapshotJMAP(ctx context.Context) (*Snapshot, error) {
 	}, nil
 }
 
+// describeJMAPError turns a JMAP method-level error into something an
+// operator can act on.
+//
+// "forbidden" gets special handling because of where it shows up: against a
+// freshly migrated instance, an account that held the admin role before the
+// migration was refused x:Account/query afterwards. Whether the role failed
+// to carry over or v0.16 requires different permissions was not isolated,
+// but the operator's situation is the same either way - they have an admin
+// account that can no longer administer - and a bare "forbidden" gives them
+// nothing to go on.
+func describeJMAPError(method string, args json.RawMessage) error {
+	var parsed struct {
+		Type        string `json:"type"`
+		Description string `json:"description"`
+	}
+	if err := json.Unmarshal(args, &parsed); err != nil || parsed.Type == "" {
+		return fmt.Errorf("stalwartapi: %s error: %s", method, args)
+	}
+	if parsed.Type == "forbidden" {
+		return fmt.Errorf("stalwartapi: %s was refused (forbidden): %s - this account is authenticated but not "+
+			"permitted to perform management operations. After a v0.16 migration this is worth checking first: an "+
+			"account that held the admin role beforehand may not have it afterwards",
+			method, parsed.Description)
+	}
+	if parsed.Description != "" {
+		return fmt.Errorf("stalwartapi: %s error (%s): %s", method, parsed.Type, parsed.Description)
+	}
+	return fmt.Errorf("stalwartapi: %s error: %s", method, parsed.Type)
+}
+
 func accountQueryIDs(responses []methodResponse) ([]string, error) {
 	if len(responses) == 0 {
 		return nil, fmt.Errorf("stalwartapi: Account/query returned no method responses")
 	}
 	r := responses[0]
 	if r.Name == "error" {
-		return nil, fmt.Errorf("stalwartapi: Account/query error: %s", r.Args)
+		return nil, describeJMAPError("Account/query", r.Args)
 	}
 	var result struct {
 		IDs []string `json:"ids"`
@@ -228,7 +260,7 @@ func accountGetList(responses []methodResponse) ([]account, error) {
 	}
 	r := responses[0]
 	if r.Name == "error" {
-		return nil, fmt.Errorf("stalwartapi: Account/get error: %s", r.Args)
+		return nil, describeJMAPError("Account/get", r.Args)
 	}
 	var result struct {
 		List []account `json:"list"`