// The CLI's extra-hostname API (#151): the verbs that attach a customer's
// own hostname to an app's route, as a data write in the deployment bucket,
// so an app holding no AWS credentials and no box access can offer
// custom-domain hosting to ITS customers in one call. The claim it writes is
// the whole authorization; the agent's domains pass turns it into an alias
// row, on the box that actually owns the route.
//
// Attach, detach and the prefix-map publish go through domainsGate, below —
// the instance family's principal, binding and readiness checks, but with the
// instance-verb WORKLOAD budget swapped for a CONVERGENCE-RATE ceiling
// (domainsCeilingBurst, spec §4a): a Pages hub with wildcard DNS makes no
// per-repo hostname call at all, so gating these on the per-minute instance
// budget would uplift a call that isn't the workload that budget was sized
// for. The exemption applies to every principal, person and service alike —
// it was never about who is calling, only about what the door is. A debugging
// session chasing a 429 here wants domainsCeilingBurst, not cliInstanceBurst.
//
// The rest of the gate IS the instance family's, verbatim: the same bearer
// shapes reach it, and every refusal before the ceiling is the same
// byte-identical 404. That reuse is deliberate: titogo's router calls this
// door with its CARLOS_INSTANCE_TOKEN, the very credential it already holds
// for instances, and a second hand-rolled gate here would be a second place
// for the ordering (principal, budget, readiness) to drift.
//
// Two neutralities this file exists to keep:
//   - a hostname another account holds answers 409 "hostname unavailable" and
//     NOTHING else — not who holds it, not which account, not whether the
//     holder is in this deployment at all;
//   - detach is quiet in both directions — an unknown hostname and another
//     owner's hostname answer with the identical 200 body, so detach is not a
//     way to ask "does anyone own this?".
//
// Spec: docs/superpowers/specs/2026-08-12-route-extra-hostnames-design.md §5.
package console

import (
	"context"
	"errors"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
	"slices"
	"sort"
	"strconv"
	"strings"
	"time"

	"github.com/carlosframework/platform/internal/certwarm"
	"github.com/carlosframework/platform/internal/domains"
	"github.com/carlosframework/platform/internal/edgesfile"
	"github.com/carlosframework/platform/internal/hostops"
	"github.com/carlosframework/platform/internal/provision"
	"github.com/carlosframework/platform/internal/release"
	"github.com/carlosframework/platform/internal/status"
)

// consoleHosts are the hostnames this console itself answers on: the ORIGIN
// host, plus the REDIRECT HOSTS (CONSOLE_REDIRECT_HOSTS: retired console
// origins such as tito's carlos.tito.io, which this console still answers on
// and 301s to Origin). Every deployment refuses these whether or not it
// reserves platform domains (domainHostDenied). The reason is self-harm, not
// tenant isolation: an alias on one of these names points the console's own
// address at an app. Route-wins ordering on a box does not prevent that. It
// is per-box, and it stops protecting the name when a second box
// materializes the alias.
//
// Only the names themselves are refused on every deployment. Everything
// under them is refused only with ReservePlatformDomains (see
// deniedDomains). A self-hosted console at carlos.example.com whose apps
// live at <app>.carlos.example.com must be able to attach
// blog.carlos.example.com.
//
// The redirect entries go through the same normalizeHost that ServeHTTP's
// retired-host check uses, so the two readings of CONSOLE_REDIRECT_HOSTS
// cannot disagree. NewServer refuses a redirect host equal to the origin.
func (s *Server) consoleHosts() []string {
	hosts := make([]string, 0, len(s.cfg.RedirectHosts)+1)
	if u, err := url.Parse(s.cfg.Origin); err == nil {
		if h := strings.ToLower(u.Hostname()); h != "" {
			hosts = append(hosts, h)
		}
	}
	for _, h := range s.cfg.RedirectHosts {
		if h = normalizeHost(h); h != "" {
			hosts = append(hosts, h)
		}
	}
	return hosts
}

// The /domains door refuses whole subtrees in two tiers (#209), and the
// tier decides who may ever get past it.
//
// platformDomains are the deployment's OWN zones. Members are refused them;
// a platform operator may attach one to an app through the --platform door,
// because these are exactly the names an operator runs their own site on
// (carloku.com on the flagship, go.tito.io on Tito's):
//
//   - the operator's CONSOLE_DENY_DOMAINS entries. An operator who lists a
//     name has chosen to refuse it to tenants;
//   - with ReservePlatformDomains, everything UNDER the console's own
//     hostnames (consoleHosts). On a shared platform those names belong to
//     the operator, not to a tenant.
//
// reservedDomains are refused to everyone, the operator included, because a
// claim on any of them takes an address the platform itself or another
// tenant stands on:
//
//   - the STEERING HOST (default edge.<apps-domain>), platform
//     infrastructure;
//   - the TUNNEL HOST (CARLOS_TUNNEL_HOST), the fleet hub's own address,
//     which the edge Allows with no registry route behind it;
//   - with ReservePlatformDomains, the APPS DOMAIN, the whole tenant
//     namespace (<app>.<sqid>.<apps-domain>). Every app's public URL is
//     under it, so a claim there is one tenant taking another tenant's
//     address. This is the sibling-apex hazard that handleAPIInstanceCreate
//     refuses within an account, refused here across the deployment. Hosts
//     under the apps domain are what `carlos instances` is for.
//
// The console's own hostnames are refused by exact name, to everyone, in
// domainHostPolicy.
//
// Without ReservePlatformDomains (CONSOLE_RESERVE_PLATFORM_DOMAINS) neither
// derived rule is added. That is the default because a self-hosted
// deployment usually puts its console, its apps domain and its custom
// domains in ONE zone that ONE person owns, and the reserved rules refused
// ordinary names there. Existing routes are still safe without it:
// deploymentRouteTaken refuses a hostname that another app's route already
// uses. With it set, these are the rules for a platform that hosts apps for
// OTHER people, such as the flagship or carloku (spec §5: "all derived from
// console/deployment config, not hardcoded").
//
// exemptAppsDomain is the CONSOLE_APPS_DOMAIN_ALIAS_ACCOUNTS delegation
// (domainHostPolicy). It drops, from both tiers, every entry that is the
// apps domain or an ancestor of it, so that a delegated one-label alias is
// not refused by a blanket entry above it.
//
// Derived per call rather than cached at boot: one url.Parse and a short
// copy, on a door that then does bucket I/O. This keeps it correct for an
// embedder (or a test) that changes the config after NewServer.
func (s *Server) platformDomains(exemptAppsDomain bool) []string {
	entries := slices.Clone(s.cfg.DenyDomains)
	if s.cfg.ReservePlatformDomains {
		entries = append(entries, s.consoleHosts()...)
	}
	return s.denyEntries(entries, exemptAppsDomain)
}

// reservedDomains: see platformDomains.
func (s *Server) reservedDomains(exemptAppsDomain bool) []string {
	domain := strings.ToLower(strings.TrimSpace(s.cfg.AppsDomain))
	steeringHost := strings.TrimSuffix(normalizeHost(strings.TrimSpace(s.cfg.SteeringHost)), ".")
	if steeringHost == "" && domain != "" {
		steeringHost = "edge." + domain
	}
	entries := []string{strings.TrimSuffix(s.cfg.TunnelHost, ".")}
	if s.cfg.ReservePlatformDomains {
		entries = append(entries, domain)
	}
	// The steering host is never exempt: it is edge.<apps-domain>, under
	// the apps domain rather than above it, and a delegated alias account
	// must not be able to take it.
	deny := s.denyEntries(entries, exemptAppsDomain)
	if steeringHost != "" {
		deny = append(deny, steeringHost)
	}
	return deny
}

// denyEntries normalizes entries, dropping blanks (an empty entry would be
// one no hostname could avoid matching) and, when exemptAppsDomain is set,
// every entry that is the apps domain or an ancestor of it.
func (s *Server) denyEntries(entries []string, exemptAppsDomain bool) []string {
	domain := strings.ToLower(strings.TrimSpace(s.cfg.AppsDomain))
	covers := func(entry string) bool {
		return entry == domain || (entry != "" && strings.HasSuffix(domain, "."+entry))
	}
	deny := make([]string, 0, len(entries)+1)
	for _, entry := range entries {
		entry = strings.ToLower(strings.TrimSpace(entry))
		if entry == "" || (exemptAppsDomain && covers(entry)) {
			continue
		}
		deny = append(deny, entry)
	}
	return deny
}

// resolveAliasRoute decides which of the app's routes a claim points at.
// ok=false means a response has already been written.
//
// An EXPLICIT route is shape-checked and then accepted as given. The door
// deliberately does not verify that the route exists: instance records are
// only one way a route comes to be, and an operator-minted route (tito's
// go.tito.io, every route on a self-hosted box) has no record at all —
// refusing those here would make the feature unusable for exactly the
// deployment that asked for it. The authoritative check is on the box, at
// reconcile: a claim naming a route that box does not own materializes
// nothing (spec §3), so a wrong route is inert rather than dangerous.
//
// An OMITTED route is defaulted only when there is exactly one thing it could
// mean — the app's single instance record. Zero or several is refused, naming
// the flag that resolves it: guessing an app's primary route out of a set
// would attach a customer's hostname to whichever one sorted first.
func (s *Server) resolveAliasRoute(ctx context.Context, w http.ResponseWriter, acct *Account, app, want string) (string, bool) {
	if route := strings.ToLower(strings.TrimSpace(want)); route != "" {
		if !provision.ValidHostShape(route) {
			jsonError(w, http.StatusBadRequest, "invalid route hostname")
			return "", false
		}
		return route, true
	}
	recs, _, err := provision.ListRecords(ctx, s.cfg.Releases, acct.Sqid, app, instanceListMax)
	if err != nil {
		log.Printf("console: api domains route default %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not read this app's instances")
		return "", false
	}
	if len(recs) == 1 {
		return recs[0].Host, true
	}
	if len(recs) == 0 {
		jsonError(w, http.StatusBadRequest,
			"specify --route: the app has no instance records to default to — name the route hostname to attach to")
		return "", false
	}
	jsonError(w, http.StatusBadRequest,
		"specify --route: the app has "+strconv.Itoa(len(recs))+" instances")
	return "", false
}

// domainsGate is instanceGate's principal, binding and readiness checks with
// the instance-verb WORKLOAD budget step replaced by a CONVERGENCE-RATE
// ceiling (spec §4a, sharpened by Task 5 review C34). Wildcard DNS changes
// the WORKLOAD question: a Pages hub with wildcard DNS makes NO per-repo
// hostname call at all — one claim on the hub host with both flags, and
// every repo's subdomain serves off the catchall — so gating attach and
// detach on the instance family's per-minute request budget would uplift a
// call that makes no per-repo call at all. That is the whole of what the
// exemption establishes: the legitimate workload does not NEED a budget. It
// does not establish that no budget is safe — every EFFECTIVE attach or
// detach audits and bumps control/serial, which every box polls at 2s and
// reacts to with a full pass, so an unlimited exempt door would let one
// authenticated credential drive fleet-wide convergence at request rate.
// allowDomains (domainsCeilingBurst, svcprincipal.go) is that ceiling: high
// enough that no real caller — including the exempt wildcard workload
// itself — ever notices it, low enough that it still caps how fast one
// credential can make every box look at the world again.
//
// The other thing bounded on this path is the FAILING half of a wildcard
// enable, bounded separately, inside setDomainCapabilities (wildFailBurst)
// — a live, sequential DNS round trip on the request path is a hazard
// whether or not this ceiling would eventually have caught it too.
func (s *Server) domainsGate(w http.ResponseWriter, r *http.Request) (Principal, *Account, string, bool) {
	_, acct, app, ok := s.apiAccountApp(w, r)
	if !ok {
		return Principal{}, nil, "", false
	}
	p, _ := principalFrom(r.Context())
	if !s.allowDomains(p, time.Now()) {
		jsonError(w, http.StatusTooManyRequests, "too many requests — wait a minute and try again")
		return Principal{}, nil, "", false
	}
	// A console with no deployment bucket configured can answer none of
	// these — instanceGate's own check, kept here since this gate stops
	// short of calling it.
	if s.cfg.Releases == nil {
		jsonError(w, http.StatusServiceUnavailable,
			"no deployment bucket on this host — the console is running without one")
		return Principal{}, nil, "", false
	}
	return p, acct, app, true
}

// handleAPIDomainAttach is the point of the feature: one claim written to the
// bucket, in the spec's refusal order — gate, body, hostname, deny list,
// route, write. Idempotent by design (the titogo contract): re-attaching a
// hostname this app already holds is 200 with created false, converging the
// route if it moved, and a hostname anyone ELSE holds is the neutral 409.
//
// The optional kind/channel body fields are `carlos deploy`'s first-route
// extras (#82): kind "static" routes the attach through the shared
// attachDomain core (domainattach.go) instead of the route-defaulting below
// (which needs an instance record a static app never has). The core itself
// decides what the attach means — an app holding a ready route gets an
// alias claim naming it; one holding none gets the claim AND a declared
// static provision record the reconciler materializes as the app's first
// route. route and kind together are refused: an alias target and a
// first-route mint are two different instructions.
func (s *Server) handleAPIDomainAttach(w http.ResponseWriter, r *http.Request) {
	p, acct, app, ok := s.domainsGate(w, r)
	if !ok {
		return
	}
	if s.refuseTemporary(w, acct, app, "attach a domain to it") {
		return
	}
	// The CREATE half of the provision-record lifecycle, reached through
	// this door rather than the instance one: the first-route branch below
	// writes a declared provision.Record (attachDomain, domainattach.go),
	// and a record is what transfers reconciler authority over the app's
	// route. `POST .../instances` already refuses a service for exactly
	// that; leaving this open would let a CI credential acquire the same
	// authority by taking the other door.
	//
	// SERVICE-ONLY, not outright, and the split is the one the flag draws
	// everywhere it can: a person attaching a domain to the control plane is
	// an ordinary operator act — the same class as writing its instance
	// record — while a CI credential doing it is the console's route being
	// claimed by something with no standing to claim it. Detach is the
	// asymmetric one (refused outright) because REMOVAL is destruction.
	//
	// Placed straight after domainsGate, which puts it after the family's
	// byte-identical 404 and before EVERY branch's write — the static branch
	// that delegates to the shared core as well as the alias branch below.
	// It does not disturb the neutrality ordering the alias branch's own
	// comment protects: that refusal is about which HOSTS exist, readable by
	// any caller, whereas this one fires only for a service that is already
	// a proven binding of this account and app, and tells it only what the
	// promote door would tell it anyway.
	//
	// The browser twin (handleAppDomainAttach, appdomains.go) needs no
	// counterpart: it authenticates a session, so its principal is always a
	// person and this refusal could never fire there. The shared core
	// takes an audit-actor STRING rather than a Principal, which is the same
	// fact stated in the types.
	if s.refuseServiceControlPlane(w, p, acct.ID, app, "attach a domain to it") {
		return
	}
	principal := auditActor(p, acct)
	var in struct {
		Host    string `json:"host"`
		Route   string `json:"route"`
		Kind    string `json:"kind"`
		Channel string `json:"channel"`
		Message string `json:"message"`
		// Wildcard and Catchall are the woodstar-carloku capability flips
		// (Task 5), decoded as pointers so an ABSENT field means "leave
		// unchanged" — the same tri-state rule apps place's -target and
		// instances' converge flags already live by. nil never reaches
		// SetClaimCapabilities: setDomainCapabilities below reads the
		// claim's current values first and only overrides the one(s) the
		// caller actually named.
		Wildcard *bool `json:"wildcard,omitempty"`
		Catchall *bool `json:"catchall,omitempty"`
		// Platform asks for the operator's door (#209): with it, a hostname
		// in the deployment's own zones (hostPlatform) may be attached. It
		// lifts nothing else. Reserved names stay refused, and the caller
		// must still be in this account (domainsGate).
		Platform bool `json:"platform,omitempty"`
	}
	if !readJSON(w, r, &in) {
		return
	}
	if s.cfg.HostClaim && (in.Wildcard != nil || in.Catchall != nil) {
		jsonError(w, http.StatusConflict, claimRefusalText(errClaimAliasCapabilitiesUnsupported))
		return
	}
	message, ok := checkedActivityMessage(w, in.Message)
	if !ok {
		return
	}
	// Decided from the caller and the flag alone, before the hostname is
	// read, so the answer cannot vary with what the deny list holds.
	if in.Platform && !s.principalPlatformOperator(p) {
		jsonError(w, http.StatusForbidden, platformOperatorMsg)
		return
	}
	// "*.<parent>" is an instance catch-all (domaincatchall.go), not a
	// hostname: it names no route, carries no capabilities and has no
	// platform form, so every other field is refused rather than ignored.
	// A person's act, like `carlos instances enable`: a catch-all is
	// standing policy over every unclaimed name under parent, which a
	// credential the app holds must not be able to set for itself.
	if parent, ok := domains.ParseInstanceCatchallHost(in.Host); ok {
		if !s.apiPerson(w, r) {
			return
		}
		if in.Route != "" || in.Kind != "" || in.Channel != "" || in.Wildcard != nil || in.Catchall != nil || in.Platform {
			jsonError(w, http.StatusBadRequest,
				"an instance catch-all takes no route, kind, channel, wildcard, catchall or platform — it serves each instance at <label>."+parent)
			return
		}
		ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
		defer cancel()
		if ref := s.catchallAppReady(ctx, acct, app); ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
		created, ref := s.attachInstanceCatchall(ctx, acct, app, parent, principal, message)
		if ref != nil {
			jsonError(w, ref.Status, ref.Msg)
			return
		}
		writeJSON(w, http.StatusOK, map[string]any{
			"host": domains.InstanceCatchallHost(parent), "route": "", "created": created, "instances": true,
		})
		return
	}
	// Path-traversal defence stated as such: this hostname becomes a bucket
	// key segment (domains/<host>.json) and, on the box, a registry alias row
	// and a certificate name. Nothing below runs until it is a well-formed,
	// lowercased, dot-bearing hostname.
	host, ok := domains.NormalizeAliasHost(in.Host)
	if !ok {
		jsonError(w, http.StatusBadRequest,
			"invalid hostname — attach a full hostname like tickets.example.com")
		return
	}
	if policy := s.domainHostPolicy(host, acct.Sqid); policy == hostReserved || (policy == hostPlatform && !in.Platform) || (s.directAppsDomainHost(host) && ((in.Wildcard != nil && *in.Wildcard) || (in.Catchall != nil && *in.Catchall))) {
		jsonError(w, http.StatusBadRequest, "that hostname is platform-managed")
		return
	}
	if in.Kind != "" && in.Route != "" {
		jsonError(w, http.StatusBadRequest,
			"route and kind are two different instructions — name a route to alias, or a kind to mint, not both")
		return
	}
	if in.Kind != "" && in.Kind != "static" {
		jsonError(w, http.StatusBadRequest, "kind must be \"static\"")
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// The caller's own PENDING first-route claim (#215): a plain re-attach
	// is how it gets verified, and only the first-route core knows how —
	// look for the proof, and declare the record once it is there. Without
	// this the own-first-route short-circuit below would answer for it
	// without ever looking, and the CLI would read that as attached. Own
	// claim only, so it reveals nothing the list door does not.
	if want := strings.ToLower(strings.TrimSpace(in.Route)); in.Kind == "" && (want == "" || want == host) {
		if cur, err := domains.GetClaim(ctx, s.cfg.Releases, host); err == nil &&
			cur.Account == acct.Sqid && cur.App == app && cur.Route == "" && cur.Pending {
			in.Kind, in.Route = "static", ""
		}
	}
	if in.Kind == "static" {
		// No deployment-route check here: this branch delegates to
		// attachDomain, which carries the guard immediately before each of
		// its own AttachClaim calls — below attachChannel and every other
		// gate that can refuse first. One placed HERE would sit above them
		// and be read apart from the ordinary 409 by a prober sending a
		// deliberately malformed channel (Task 5 review round 2).
		// The shared core decides alias-vs-first-route itself (readyRouteHost
		// is ITS question — no pre-read here): a ready route makes this an
		// ordinary alias claim naming it, none makes the host the app's
		// first route (claim + declared static record). The answer comes
		// from the core's result: on the first-route branch the host IS the
		// route the record just declared; on the alias branch it is the
		// route the claim names.
		res, ref := s.attachDomainAs(ctx, acct, app, host, in.Kind, in.Channel, principal, in.Platform, message)
		if ref != nil {
			setNoCapacityRetryAfter(w, ref)
			jsonError(w, ref.Status, ref.Msg)
			return
		}
		route := res.Claim.Route
		if res.FirstRoute || (res.Pending && route == "") {
			route = host
		}
		if res.OperationID != "" {
			answer := attachAnswer(host, route, res.Created, res.Pending, res.Verify)
			answer["operation_id"], answer["phase"] = res.OperationID, res.OperationPhase
			writeJSON(w, http.StatusAccepted, answer)
			return
		}
		writeJSON(w, http.StatusOK, attachAnswer(host, route, res.Created, res.Pending, res.Verify))
		return
	}
	// A first-route claim this app already holds stays first-route. Without
	// this, a re-attach naming no route (how a member flips --wildcard or
	// --catchall on it) reached resolveAliasRoute, which defaults to the
	// app's single instance record — for a first-route app, the record the
	// claim itself declared, at this very host — and AttachClaim then
	// converged the claim into an alias of its own host. That self-alias
	// still served, but every box pass logged it as shadowed by a real
	// route, and detach no longer removed the record (its first-route
	// branch keys on an empty Route), so the route outlived the claim.
	// Naming the host itself as --route means the same thing and is treated
	// the same way: a hostname cannot alias itself.
	//
	// Only the caller's OWN claim takes this branch, so it reveals nothing
	// the list door does not already show them; every other case falls
	// through to the ordinary path and its neutral refusals unchanged.
	if want := strings.ToLower(strings.TrimSpace(in.Route)); want == "" || want == host {
		if cur, err := domains.GetClaim(ctx, s.cfg.Releases, host); err == nil &&
			cur.Account == acct.Sqid && cur.App == app && cur.Route == "" {
			if in.Wildcard != nil || in.Catchall != nil {
				if !s.setDomainCapabilities(w, r, ctx, acct, app, p, host, in.Wildcard, in.Catchall) {
					return
				}
			}
			writeJSON(w, http.StatusOK, map[string]any{"host": host, "route": host, "created": false})
			return
		}
	}
	route, ok := s.resolveAliasRoute(ctx, w, acct, app, in.Route)
	if !ok {
		return
	}
	// The deployment-route refusal sits HERE, immediately before the claim
	// write and strictly AFTER resolveAliasRoute — never above it.
	//
	// Byte-identical bodies are not enough on their own; ORDER is half of
	// the neutrality (Task 5 review). When this check ran before
	// resolveAliasRoute, the pre-existing "someone else holds it" 409 was
	// reachable only after it, so a prober could tell the two apart by
	// deliberately failing the LATER gate and reading which refusal came
	// back first:
	//
	//	{"host":"<probe>","route":"!!"}  -> 409 if <probe> is a live route,
	//	                                   400 "invalid route hostname" if not
	//	{"host":"<probe>"} from an app with no instance records
	//	                                -> 409 if <probe> is a live route,
	//	                                   400 "specify -route: ..." if not
	//
	// Both are side-effect-free and enumerate the deployment's non-alias
	// route set one hostname at a time, inside the ceiling — exactly the
	// existence oracle this file's header forbids. Behind every gate that
	// can refuse first, the two 409s are indistinguishable in status, body
	// AND reachability. Anything added to this branch later belongs above
	// this line, not below it.
	// Plans 3a: custom domains need a plan that includes them (above
	// heldElsewhere, per the rule).
	if ref := s.customDomainRefusal(acct, host); ref != nil {
		writeJSON(w, ref.Status, capOrError(ref))
		return
	}
	if ref := s.heldElsewhere(ctx, host, acct.Sqid, app); ref != nil {
		jsonError(w, ref.Status, ref.Msg)
		return
	}
	created, changed, pending, err := s.attachDomainClaim(ctx, acct, app, domains.Claim{
		Host: host, Account: acct.Sqid, App: app, Route: route,
		// UTC, like every other timestamp written to the bucket: these claims
		// are read on boxes in other regions.
		CreatedAt: time.Now().UTC().Format(time.RFC3339), CreatedBy: principal,
		// Wildcard and Catchall are deliberately NOT populated from `in`
		// here, even though the request body may carry them: AttachClaim's
		// create path marshals this literal verbatim, so any value placed on
		// it lands with no CNAME gate and no delegation-zone check. The only
		// legal writer of these two fields is SetClaimCapabilities, called
		// below, AFTER this write has already established ownership (a
		// review finding on Task 1 — an attach body smuggling
		// "wildcard":true alongside host/route must not reach this literal).
	}, time.Now(), s.domainProver(ctx, host, acct.Sqid))
	if errors.Is(err, domains.ErrHostUnavailable) {
		// Exactly these bytes, whoever holds it: naming the holder — or even
		// distinguishing "held by another app of yours" from "held by a
		// stranger" — would make this door a hostname-ownership oracle.
		jsonError(w, http.StatusConflict, hostUnavailableMsg)
		return
	} else if msg, ok := claimAliasRefusal(err); ok {
		jsonError(w, http.StatusConflict, msg)
		return
	} else if errors.Is(err, hostops.ErrPending) {
		w.Header().Set("Retry-After", "2")
		jsonError(w, http.StatusConflict, claimRetireBusyMsg)
		return
	} else if err != nil {
		log.Printf("console: api domains attach %s/%s %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not attach the hostname — try again")
		return
	}
	// Only an actual WRITE audits and announces (spec §5), the same rule
	// detach observes below. `created` is the caller's answer; `changed` is
	// this one, and they differ on the converge — a re-attach that repointed
	// the route created nothing but must reach the fleet. The no-op case is
	// not hypothetical: titogo's router re-attaches every hostname on each
	// reload pass, so a bump per call would keep every box converging onto
	// nothing and an audit row per call would bury the tenant's log.
	if changed {
		s.auditActivity(acct, app, principal, Activity{
			Action: "domain-attach", TargetType: "instance", Target: route, Message: message,
			Detail: "attached hostname " + host + " -> " + route + platformNote(in.Platform) + pendingNote(pending) + " (cli)",
		})
		// The claim is what a box's domains pass mints an alias row from, so
		// this is a box-consumed write (carlos-deploy §3): announce it, and
		// the hostname is serving seconds after the call instead of on the
		// hour. Strictly after the write and the audit — a serial that moved
		// for a write that failed would send every box looking for nothing.
		// Not for a pending claim, which every box skips (#215).
		if !pending {
			s.bumpSerial(ctx)
		}
	}
	// Capability flip: only when the caller actually named one of the two
	// fields — a bare attach (both nil) must never touch Wildcard/Catchall,
	// the same "absent means unchanged" contract the CLI's fs.Visit-gated
	// flags rely on.
	if in.Wildcard != nil || in.Catchall != nil {
		if !s.setDomainCapabilities(w, r, ctx, acct, app, p, host, in.Wildcard, in.Catchall) {
			return
		}
	}
	writeJSON(w, http.StatusOK, attachAnswer(host, route, created, pending, s.domainChallenge(host, acct.Sqid)))
}

// attachAnswer is the attach door's 200 body. verified is always present
// (#215): false means the claim is stored but reserved, not served, until
// the TXT record in verify is published and the attach is repeated. verify
// is sent only then, so a client that predates the field sees exactly the
// body it always did for an ordinary attach.
func attachAnswer(host, route string, created, pending bool, verify dnsRecord) map[string]any {
	out := map[string]any{"host": host, "route": route, "created": created, "verified": !pending}
	if pending {
		out["verify"] = verify
	}
	return out
}

// wildFailMsg is the ONE 429 body both the peek (wildFailTripped) and the
// consume (allowWildFail) refusals in setDomainCapabilities answer with — a
// caller must not be able to tell which of the two turned it away, since
// both mean exactly the same thing to them: stop retrying for a minute.
const wildFailMsg = "too many wildcard attempts with no _acme-challenge CNAME in place — wait a minute and retry"

// setDomainCapabilities applies an attach body's optional wildcard/catchall
// flip AFTER the underlying claim attach above has already succeeded and
// established ownership. ok=false means a response has already been
// written — the same resolveAliasRoute convention this file already uses.
//
// Absent fields mean "leave unchanged": the door reads the claim's CURRENT
// capabilities as the baseline and overrides only the field(s) the caller
// actually named, so a caller flipping catchall alone cannot accidentally
// clear an already-enabled wildcard, and vice versa.
func (s *Server) setDomainCapabilities(w http.ResponseWriter, r *http.Request, ctx context.Context, acct *Account, app string, p Principal, host string, wantWildcard, wantCatchall *bool) (ok bool) {
	if s.cfg.HostClaim {
		jsonError(w, http.StatusConflict, claimRefusalText(errClaimAliasCapabilitiesUnsupported))
		return false
	}
	principal := auditActor(p, acct)
	cur, err := domains.GetClaim(ctx, s.cfg.Releases, host)
	if err != nil {
		log.Printf("console: api domains capabilities %s/%s %s: read after attach: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not update the hostname's capabilities — try again")
		return false
	}
	wildcard, catchall := cur.Wildcard, cur.Catchall
	if wantWildcard != nil {
		wildcard = *wantWildcard
	}
	if wantCatchall != nil {
		catchall = *wantCatchall
	}
	// enabling is the false->true TRANSITION only — re-sending wildcard:true
	// for a claim that already has it must not re-run the gate. Two reasons:
	// the CNAME lookup is a live, sequential, request-path DNS round trip
	// (IMPORTANT-2, Task 5 review), and titogo's router re-attaches every
	// hostname (with whatever capability flags it was minted with) on every
	// reload pass — gating on the transition is what keeps a resolver blip
	// from 422ing an otherwise idempotent, already-successful re-attach.
	enabling := wantWildcard != nil && *wantWildcard && !cur.Wildcard
	switch {
	case wantWildcard != nil && !*wantWildcard:
		// Disabling wildcard cascades catchall off in the SAME call —
		// turning off never requires DNS, and a caller disabling wildcard is
		// not asking for a 422. The door normalizes here rather than calling
		// SetClaimCapabilities with catchall still true and letting its own
		// ErrCatchallNeedsWildcard refuse a request that was never asking to
		// enable anything.
		catchall = false
	case enabling:
		// Enabling wildcard requires a configured delegation zone and a live
		// _acme-challenge CNAME delegating to it — the claim-derived-
		// wildcards spec's ACME story (§4): this deployment's own zone
		// issues the wildcard cert, so it must control the challenge record.
		if s.delegationZone == "" {
			jsonError(w, http.StatusUnprocessableEntity, "deployment has no delegation zone configured")
			return false
		}
		// PEEKED before the DNS round trip (C33 review): once a principal
		// has already tripped wildFail, running the lookup again buys the
		// caller nothing but costs the console another live, sequential
		// outbound DNS call. A caller who has never failed never trips
		// this — wildFailTripped only ever reads TRUE from a count that
		// CONSUMED (below) put there — so this can never turn away a
		// legitimate, exempt caller.
		if s.wildFailTripped(p, time.Now()) {
			jsonError(w, http.StatusTooManyRequests, wildFailMsg)
			return false
		}
		if !s.delegationCNAMEDelegated(ctx, host) {
			// CONSUMED only here, on an ACTUAL failure (spec §4a). A
			// succeeding enable is once-per-domain and exempt (domainsGate
			// carries only the convergence ceiling, not a workload budget);
			// a failure is what the peek above exists to eventually stop
			// paying for. Counted AFTER the lookup, so the bound is on
			// FAILURES rather than on attempts — a caller whose CNAME is
			// correct never meets it at all.
			if !s.allowWildFail(p, time.Now()) {
				jsonError(w, http.StatusTooManyRequests, wildFailMsg)
				return false
			}
			jsonError(w, http.StatusUnprocessableEntity,
				"create CNAME _acme-challenge."+host+" -> _acme-challenge."+host+"."+s.delegationZone+", then retry")
			return false
		}
	}
	if s.directAppsDomainHost(host) && (wildcard || catchall) {
		jsonError(w, http.StatusBadRequest, "that hostname is platform-managed")
		return false
	}
	capChanged, err := domains.SetClaimCapabilities(ctx, s.cfg.Releases, host, acct.Sqid, app, wildcard, catchall)
	if errors.Is(err, domains.ErrCatchallNeedsWildcard) {
		jsonError(w, http.StatusUnprocessableEntity, err.Error())
		return false
	} else if errors.Is(err, domains.ErrHostUnavailable) {
		// The family's byte-identical 404 discipline, copied verbatim (not
		// jsonError — a distinct shape here would itself be a tell). This
		// fires only after the attach above already proved ownership, so in
		// practice it means the claim changed hands between that write and
		// this one — vanishingly rare, but the response must still leak
		// nothing to whoever is now asking.
		http.NotFound(w, r)
		return false
	} else if err != nil {
		log.Printf("console: api domains capabilities %s/%s %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not update the hostname's capabilities — try again")
		return false
	}
	if capChanged {
		s.audit(acct, app, principal, "domain-capabilities",
			fmt.Sprintf("set %s wildcard=%v catchall=%v (cli)", host, wildcard, catchall))
		s.bumpSerial(ctx)
		// #165's exported index-writer is called here once it lands — a
		// capability flip must reach the fast-path claims index (see plan:
		// claim-derived-wildcards, Task 5 addendum).
	}
	return true
}

// delegationCNAMEDelegated reports whether host's _acme-challenge CNAME
// already points at this deployment's delegation zone — the same check the
// attach gate and the list stamp both use, so a claim's delegation_status
// can never disagree with what an attach would decide right now. Both sides
// are trailing-dot-normalized before comparing: net.DefaultResolver's
// LookupCNAME answers with a fully-qualified name (trailing dot), a hand-
// typed zone rarely carries one, and the comparison must not care which.
// The comparison is also case-INsensitive (strings.EqualFold): DNS names
// compare case-insensitively by definition (RFC 4343), and a resolver
// answers in the record's own authored case — a customer who typed their
// CNAME target in mixed case must not read as a permanently broken
// delegation.
func (s *Server) delegationCNAMEDelegated(ctx context.Context, host string) bool {
	got, err := s.lookupCNAME(ctx, "_acme-challenge."+host)
	if err != nil {
		return false
	}
	want := "_acme-challenge." + host + "." + s.delegationZone
	return strings.EqualFold(strings.TrimSuffix(got, "."), strings.TrimSuffix(want, "."))
}

// maxPathsBody is the byte cap on a prefix-map publish, and it is the ONE
// door in this family that cannot live inside readJSON's 8KiB: the ceiling is
// MaxPathsPerClaim entries, each a segment of up to 255 bytes pointing at a
// hostname of up to 253, which is a legitimate ~5MB body. Sized with headroom
// above that rather than to it, so the refusal a caller at the ceiling meets
// is the 422 that NAMES the cap — never a 413 whose fix ("split the request")
// is wrong advice for a map that is wholesale by contract.
const maxPathsBody = 8 << 20

// handleAPIDomainPaths answers `PUT /api/cli/apps/{account}/{app}/domains/{host}/paths`:
// publish the WHOLE prefix map for a hostname the app already claims.
//
// Wholesale by contract. The caller regenerates the map from its own database
// and publishes the result, so this replaces rather than merges — that is what
// makes a republish a full repair and lets a removal express a rollback. There
// is deliberately no per-prefix add or delete verb: two ways to write the same
// state is two ways for it to drift from the caller's own.
//
// It writes ONE field of an existing claim and creates nothing, which is what
// separates it from attach: a hostname this app does not already hold has no
// prefix map to publish, and says so with the family's neutral 404.
func (s *Server) handleAPIDomainPaths(w http.ResponseWriter, r *http.Request) {
	p, acct, app, ok := s.domainsGate(w, r)
	if !ok {
		return
	}
	// Straight after domainsGate, exactly as the attach door places its own:
	// after the family's byte-identical 404, before any read or write. A
	// prefix map on the control plane's own hostname hands a slice of the
	// console's URL space to another route — /admin served by whatever the
	// account points it at — and that is not something a CI credential
	// should be able to decide. SERVICE-ONLY, and the split is attach's: a
	// person doing it is an ordinary operator act, a machine doing it is the
	// console's own address being carved up by something with no standing.
	if s.refuseServiceControlPlane(w, p, acct.ID, app, "publish path routes for it") {
		return
	}
	principal := auditActor(p, acct)
	// Shape-checked BEFORE the key builder, exactly as the detach and get
	// doors do: a {host} segment arrives percent-decoded, so
	// "..%2f..%2finstances.json" would reach ClaimKey as a path with
	// separators in it. There is no path through this handler on which an
	// unnormalized host reaches the store.
	//
	// And before the BODY, unlike attach — whose hostname arrives in the body
	// and cannot be checked any earlier. Here the host is in the path, so
	// checking it first means a request naming a malformed one is refused
	// without first buffering up to maxPathsBody of it. No neutrality cost:
	// this check reads the URL and nothing else, so its answer cannot depend
	// on who holds the claim.
	host, ok := domains.NormalizeAliasHost(r.PathValue("host"))
	if !ok {
		jsonError(w, http.StatusBadRequest, "invalid hostname")
		return
	}
	// A prefix map on a platform hostname routes slices of the operator's
	// own site, so it is the operator's to publish (#209). From the name
	// alone, before the body or the claim is read: no neutrality cost.
	if s.domainHostPolicy(host, acct.Sqid) == hostPlatform && !s.principalPlatformOperator(p) {
		jsonError(w, http.StatusForbidden, platformOperatorMsg)
		return
	}
	// A POINTER to the map, so that an ABSENT paths field is refused rather
	// than read as an empty one. The distinction matters here in a way it
	// does not on a merging door: this write is wholesale, so a body whose
	// field name is misspelled would otherwise be an empty publish — a silent
	// clearing of every prefix on the hostname, answered with 200. An empty
	// map is a legitimate instruction and still means exactly that; it just
	// has to be said.
	var in struct {
		Paths *map[string]string `json:"paths"`
	}
	if !readJSONLimit(w, r, &in, maxPathsBody) {
		return
	}
	if in.Paths == nil {
		jsonError(w, http.StatusBadRequest,
			"send the whole prefix map as {\"paths\": {...}} — {\"paths\": {}} is how you clear it")
		return
	}
	paths := *in.Paths
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	changed, err := domains.SetClaimPaths(ctx, s.cfg.Releases, host, acct.Sqid, app, paths)
	if errors.Is(err, domains.ErrTooManyPaths) {
		jsonError(w, http.StatusUnprocessableEntity,
			fmt.Sprintf("a hostname may carry at most %d path prefixes", domains.MaxPathsPerClaim))
		return
	} else if errors.Is(err, domains.ErrBadPathPrefix) {
		jsonError(w, http.StatusUnprocessableEntity,
			"each path prefix must be a single bare segment: \"paulca\", not \"/paulca\"")
		return
	} else if errors.Is(err, domains.ErrBadPathTarget) {
		// The caller's error, not ours, so it must not land in the 502 below
		// telling them to retry a body that will fail identically forever.
		// The wrapped message names the offending entry — the one thing that
		// makes a 10,000-entry map fixable.
		jsonError(w, http.StatusUnprocessableEntity, err.Error())
		return
	} else if errors.Is(err, domains.ErrHostUnavailable) {
		// The family's byte-identical 404 discipline, copied verbatim from
		// setDomainCapabilities (not jsonError — a distinct shape here would
		// itself be a tell): a caller who does not hold this claim cannot
		// tell "somebody else holds it" from "nobody has claimed it".
		http.NotFound(w, r)
		return
	} else if err != nil {
		log.Printf("console: api domains paths %s/%s %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not update the hostname's path routes — try again")
		return
	}
	if changed {
		// The COUNT, never the map: a published map runs to MaxPathsPerClaim
		// entries, and an audit row is a sentence an operator reads, not a
		// copy of the payload. What the trail has to answer is "who moved
		// this hostname's routing, and when".
		s.audit(acct, app, principal, "domain-paths",
			fmt.Sprintf("published %d path prefixes for %s (cli)", len(paths), host))
		// A box-consumed write like every other claim write here: the
		// reconcile pass derives route_paths from this field, so announce it
		// and the flipped accounts are serving seconds after the call
		// instead of on the hour. Gated on `changed` for the reason
		// SetClaimPaths has a no-op check at all — the caller republishes
		// wholesale as a repair, and a bump per republish would keep every
		// box converging onto nothing.
		s.bumpSerial(ctx)
	}
	// The normalized host is the one thing the caller could not already
	// know; the map it just sent is not echoed back, both because it is
	// megabytes of the caller's own bytes and because nothing here derives
	// or alters it. `changed` is the same answer `created` and `removed`
	// give on the doors either side of this one.
	writeJSON(w, http.StatusOK, map[string]any{
		"host":     host,
		"prefixes": len(paths),
		"changed":  changed,
	})
}

// pathsOrEmpty renders a claim's prefix map for the wire as an object even
// when it is absent. Claim.Paths is omitempty, so nil and empty are one
// stored state; letting nil marshal to `null` would make a consumer tell two
// spellings of the same answer apart before it could iterate.
func pathsOrEmpty(paths map[string]string) map[string]string {
	if paths == nil {
		return map[string]string{}
	}
	return paths
}

// handleAPIDomainDetach releases a hostname. Always 200, whatever was there:
// `removed` reports whether this call is what removed it, and the three ways
// of removing nothing — already gone, never claimed, claimed by someone else
// — are indistinguishable on the wire (DetachClaim's own neutrality, spec
// §5). Only an EFFECTIVE removal audits and bumps the serial: a no-op changed
// nothing for a box to converge onto, and an audit row per probe would let a
// prober write to someone else's account log.
func (s *Server) handleAPIDomainDetach(w http.ResponseWriter, r *http.Request) {
	p, acct, app, ok := s.domainsGate(w, r)
	if !ok {
		return
	}
	// The NINTH control-plane door, and the same fuse as the instance
	// delete: the first-route branch below calls the very
	// provision.DeleteRecord that retires a route, on the same app, and this
	// door is reachable by a service credential (svcrole.Publish OR
	// svcrole.Instance). Guarding the instance family and leaving this open
	// would be a guard with a published way round it, which reads as
	// protection and is not — the same reasoning the account-deletion
	// refusal was built on.
	//
	// OUTRIGHT, and NOT conditional on the record-deleting branch. Two
	// reasons. A conditional guard is a bug surface: it would have to
	// re-derive "does this claim mint the route" ahead of the code that
	// derives it, and the two would drift. And detaching a domain from the
	// control plane is not an act anyone should perform without clearing the
	// flag first — a hostname the fleet reaches the console by is not
	// released in passing.
	//
	// Straight after domainsGate — after the family's byte-identical 404,
	// before the hostname is even normalized — so no branch reaches a write
	// without passing it, and a flagged app's answer here is CONSTANT across
	// valid and malformed hosts rather than leaking shape-validity.
	if s.refuseControlPlane(w, acct, app, "detached") {
		return
	}
	principal := auditActor(p, acct)
	// An instance catch-all is released by a person, as it was set by one,
	// and never through the first-route branch below: a catch-all has an
	// empty Route too, and that branch deletes a provision record.
	if parent, ok := domains.ParseInstanceCatchallHost(r.PathValue("host")); ok {
		if !s.apiPerson(w, r) {
			return
		}
		ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
		defer cancel()
		removed, err := s.detachInstanceCatchall(ctx, acct, app, parent, principal)
		if msg, ok := claimAliasRefusal(err); ok {
			jsonError(w, http.StatusConflict, msg)
			return
		}
		if err != nil {
			log.Printf("console: api domains detach %s/%s *.%s: %v", acct.Sqid, app, parent, err)
			jsonError(w, http.StatusBadGateway, "could not detach the hostname — try again")
			return
		}
		writeJSON(w, http.StatusOK, map[string]any{"host": domains.InstanceCatchallHost(parent), "removed": removed})
		return
	}
	// Shape-checked before the key builder, not after: a {host} segment
	// arrives percent-decoded, so "..%2f..%2finstances.json" reaches this
	// handler as a path with separators in it, and ClaimKey would happily
	// join it. There is no path through this handler on which an
	// unnormalized host reaches the store.
	host, ok := domains.NormalizeAliasHost(r.PathValue("host"))
	if !ok {
		jsonError(w, http.StatusBadRequest, "invalid hostname")
		return
	}
	// detachDomain's rule (#209): a platform hostname's claim is the
	// operator's to release. From the name alone, before the claim is read,
	// so the door's quiet-in-both-directions answer is untouched for every
	// hostname a member could hold.
	if s.domainHostPolicy(host, acct.Sqid) == hostPlatform && !s.principalPlatformOperator(p) {
		jsonError(w, http.StatusForbidden, platformOperatorMsg)
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// The first-route half (#82): a claim with an empty Route minted the
	// app's own primary route via a declared provision record, and that
	// record must go BEFORE the claim — the mirror of attach's claim-then-
	// record order, so a failure here cannot leave a record materializing a
	// route for a host anyone may now claim. Only the caller's own
	// first-route claim takes this branch; every other shape (absent,
	// another owner's, an alias) skips it silently and DetachClaim's own
	// neutrality answers as before.
	if cur, err := domains.GetClaim(ctx, s.cfg.Releases, host); err == nil &&
		cur.Account == acct.Sqid && cur.App == app && cur.Route == "" {
		if err := s.retireInstanceRecord(ctx, acct.Sqid, app, host, principal, cur.RecordIncarnation); err != nil {
			if accepted, ok := claimRetireAcceptedOf(err); ok {
				s.audit(acct, app, principal, "domain-detach", "detach of hostname "+host+" accepted, operation "+accepted.operation+" (cli)")
				s.bumpSerial(ctx)
			}
			if s.writeClaimPending(w, err) {
				return
			}
			log.Printf("console: api domains detach %s/%s %s: record delete: %v", acct.Sqid, app, host, err)
			jsonError(w, http.StatusBadGateway, "could not detach the hostname — try again")
			return
		}
	}
	removed, err := s.detachDomainClaim(ctx, host, acct.Sqid, app)
	if msg, ok := claimAliasRefusal(err); ok {
		jsonError(w, http.StatusConflict, msg)
		return
	}
	if errors.Is(err, hostops.ErrContract) {
		jsonError(w, http.StatusConflict, err.Error())
		return
	}
	if err != nil {
		log.Printf("console: api domains detach %s/%s %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not detach the hostname — try again")
		return
	}
	if removed {
		s.audit(acct, app, principal, "domain-detach", "detached hostname "+host+" (cli)")
		// Taking a hostname down is the direction people want FAST.
		s.bumpSerial(ctx)
	}
	writeJSON(w, http.StatusOK, map[string]any{"host": host, "removed": removed})
}

// domainListItem is one row of the list answer — the claim's desired state
// (host, route) joined with what the fleet actually reports for it. Status is
// "live" or "pending" and never absent; the two reading columns omit when
// unstamped, the same unknown-stays-absent convention status.AliasReading
// itself uses. Guidance is the point-your-DNS-here instruction, present
// exactly when DNSStatus is "" (no answer yet) or "elsewhere" (a real,
// wrong answer) — never "pointing" (nothing to fix) and never "unresolved"
// (our lookup failed; telling the member to create a record would blame
// them for our outage). Same condition as the console Settings page
// (domainGuidance, view.go), so `carlos deploy`'s DNS-guidance exit and the
// page a member opens next can never tell them two different stories.
// Additive: a client that predates it simply never decodes it.
type domainListItem struct {
	Host          string `json:"host"`
	Route         string `json:"route"`
	Status        string `json:"status"`
	DNSStatus     string `json:"dns_status,omitempty"`
	CertExpiresAt int64  `json:"cert_expires_at,omitempty"`
	Guidance      string `json:"guidance,omitempty"`
	// Wildcard and Catchall (Task 5) copy the claim's own capability bits
	// verbatim — always present, true or false, the same "known state"
	// convention Created/Removed use on the attach/detach answers (never
	// omitted the way an unstamped reading is).
	Wildcard bool `json:"wildcard"`
	Catchall bool `json:"catchall"`
	// DelegationStatus stamps "delegated"/"missing" from the SAME CNAME
	// check the attach gate uses, live on every list call — never cached
	// from whenever wildcard was enabled. Omitted (not "unknown") when the
	// deployment has no delegation zone configured, or the claim doesn't
	// have Wildcard: there is nothing to report in either case.
	DelegationStatus string `json:"delegation_status,omitempty"`
	// State is #299's single derived lifecycle word, with Reason (a stable
	// machine slug) and Detail (a human sentence) beside it. Always present.
	//
	// Status above is now LEGACY and frozen: it means "some non-stale box
	// reported ANY reading", which is why a row can read status "live" while
	// state is "misdirected". Both are kept because the wire is additive, but
	// every first-party surface reads State.
	State  string `json:"state"`
	Reason string `json:"reason,omitempty"`
	Detail string `json:"detail,omitempty"`
	// CheckedAt is when the reporting box last RESOLVED this hostname (unix
	// seconds), carried through from the box stamp. It is what makes a
	// mirrored state ageable: without it a consumer cannot tell a state
	// confirmed a minute ago from one confirmed before an outage began, and
	// "live" is not monotonic — a customer can change their DNS after the
	// fact. Omitted when no box has stamped a check yet.
	CheckedAt int64 `json:"checked_at,omitempty"`
	// Records is the structured form of Guidance — the same advice as data,
	// so an app need not parse the sentence. Records sharing a "set" are one
	// alternative; a client picks one set per name.
	Records []dnsRecord `json:"records,omitempty"`
	// Instances marks an instance catch-all row ("*.<parent>",
	// domaincatchall.go). Via names the catch-all a row was derived from:
	// such a row is a name the fleet reports serving for one of the app's
	// instances, not a claim of its own, so it cannot be detached by name.
	// Both additive and omitted otherwise.
	Instances bool   `json:"instances,omitempty"`
	Via       string `json:"via,omitempty"`
	// Reserves, on an instance catch-all's row, is which one-label names
	// under its parent other accounts are refused: "all" once the account
	// has proved the parent in DNS (domains.CatchallProofName), otherwise
	// "instances" — only the names of instances that exist. Additive.
	Reserves string `json:"reserves,omitempty"`
	// Verified is false for a claim whose owner has not yet proved control
	// of the hostname (#215); state is then "unverified" and Records carries
	// the TXT record that proves it, marked required. Always present.
	Verified bool `json:"verified"`
}

// handleAPIDomainList answers `carlos domains list`: this app's claims, each
// joined to the box readings sweep so the command alone verifies its own
// result (the no-infra rule) — DNS status and cert expiry as the box stamped
// them, or "pending" for a claim no live box has materialized yet.
func (s *Server) handleAPIDomainList(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	// Claims are keyed globally (domains/<host>.json — the key IS the
	// cross-account uniqueness gate), so the tenant boundary is this filter
	// and nothing else: every row that reaches the answer matched BOTH this
	// account's sqid and this app.
	claims, err := s.claims.List(ctx, s.cfg.Releases)
	if err != nil {
		log.Printf("console: api domains list %s/%s: %v", acct.Sqid, app, err)
		jsonError(w, http.StatusBadGateway, "could not list the hostnames")
		return
	}
	now := time.Now()
	readings := aliasReadings(ctx, s.cfg.Releases, now)
	// The issuer's warm-outcome records (#299 §3e), also once per call. A
	// record exists only while a host is FAILING, so this listing is one
	// object per broken hostname in the deployment and nothing at all in a
	// deployment where every domain works — it does not reintroduce the
	// per-claim cost the per-host door exists to avoid.
	warm := warmRecords(ctx, s.cfg.Releases)
	// Read ONCE per call, not per claim: dnsTargets folds the deployment's
	// edge set, and a per-claim read would refold it for every hostname.
	targets := s.dnsTargets()
	// This app's claims, host-sorted BEFORE the loop below — not just for
	// the answer's own stable order (the Store.List contract makes no
	// promise, and a terminal listing that shuffles between calls reads as
	// churn), but because the sort order also decides which claims fall
	// inside domainListCNAMELookupCap: sorting after the loop would let the
	// store's arbitrary iteration order pick a different 8 hosts every call.
	var mine []domains.Claim
	claimed := make(map[string]bool, len(claims))
	for _, c := range claims {
		claimed[c.Host] = true
		if c.Account == acct.Sqid && c.App == app {
			mine = append(mine, c)
		}
	}
	sort.Slice(mine, func(i, j int) bool { return mine[i].Host < mine[j].Host })
	out := make([]domainListItem, 0, len(mine))
	lookups := 0
	for _, c := range mine {
		// Each delegation stamp is a live, sequential, uncancellable-per-call
		// DNS round trip on the request path (lookupCNAME) — capped at
		// domainListCNAMELookupCap per list call so an app with dozens of
		// wildcard-enabled hostnames cannot turn one `carlos domains list`
		// into dozens of resolver round trips. Hosts beyond the cap (in the
		// same host-sorted order the answer itself uses) simply omit
		// delegation_status — the same "nothing to report yet" reading a
		// disabled wildcard or an unset zone already gets, never an error.
		if c.Instances {
			out = append(out, s.catchallListItems(ctx, acct, app, c, claimed, readings, warm, targets, now)...)
			continue
		}
		delegation := c.Wildcard && s.delegationZone != "" && lookups < domainListCNAMELookupCap
		if delegation {
			lookups++
		}
		out = append(out, s.domainItem(ctx, c, readings, warm[c.Host], targets, now, delegation))
	}
	writeJSON(w, http.StatusOK, map[string]any{
		"domains": out,
		// The self-describing block (#299 §2c). An app reads managed_domains
		// to know the platform owns verification and certificates here, and
		// stops implementing them itself.
		"deployment": s.domainCapability(ctx, acct.Sqid, app),
	})
}

// domainItem builds ONE claim's answer row: the claim joined to what the
// fleet reports for it, plus the derived state, guidance and records.
//
// Shared by the list door and the per-host door deliberately. The two answer
// the same question about the same hostname and must never derive it two
// ways — a consumer that refreshes one host and compares it against a listed
// row has to see the same verdict, or a mirrored status flaps for reasons
// that have nothing to do with the domain.
//
// delegation says whether to spend a live CNAME lookup on this row. The list
// door caps how many it will spend per call; the per-host door always can,
// because it is answering about exactly one host.
func (s *Server) domainItem(ctx context.Context, c domains.Claim, readings map[string]status.AliasReading, warm *certwarm.Record, targets DNSTargets, now time.Time, delegation bool) domainListItem {
	item := domainListItem{Host: c.Host, Route: c.Route, Status: "pending",
		Wildcard: c.Wildcard, Catchall: c.Catchall}
	reading, seen := readings[c.Host]
	if seen {
		item.Status = "live"
		item.DNSStatus = reading.DNSStatus
		item.CertExpiresAt = reading.CertExpiresAt
		item.CheckedAt = reading.DNSCheckedAt
	}
	item.State, item.Reason, item.Detail = claimState(c, reading, seen, warm, now)
	item.Verified = !c.Pending
	// "unresolved" means the lookup FAILED (our resolver, not the customer's
	// record) — pointing them at "create this record" guidance would blame
	// them for our outage. Only "" (no answer yet) and "elsewhere" (a real,
	// wrong answer) earn guidance.
	if item.DNSStatus != "pointing" && item.DNSStatus != "unresolved" {
		item.Guidance = domainGuidance(c.Host, targets)
		// The structured form of the SAME advice, emitted under exactly the
		// same condition so the two can never disagree about whether there is
		// anything for the member to do.
		item.Records = domainRecords(c.Host, targets, c.Wildcard, s.delegationZone)
	}
	if c.Pending {
		// The proof record, in BOTH forms, under the same lockstep rule as
		// the pointing advice above: a member reading the sentence and an
		// app reading the records must be told to create the same thing.
		v := s.domainChallenge(c.Host, c.Account)
		item.Guidance = verifyGuidance(v) + " " + item.Guidance
		item.Guidance = strings.TrimSpace(item.Guidance)
		item.Records = append(item.Records, v)
	}
	if delegation {
		if s.delegationCNAMEDelegated(ctx, c.Host) {
			item.DelegationStatus = "delegated"
		} else {
			item.DelegationStatus = "missing"
		}
	}
	return item
}

// handleAPIDomainGet answers ONE hostname — the per-host read (#299 §2e).
//
// It exists because the list door cannot carry a refresh loop: ListClaims is
// one List plus one Get per claim in the WHOLE deployment, filtered by
// account and app afterwards, so a caller refreshing one hostname pays for
// every custom domain anyone has attached. This reads exactly one object by
// key, which is what makes an on-demand refresh — or a light per-host
// re-check — defensible rather than something to warn callers off.
//
// A host this app does not own answers 404, byte-identical to a host nobody
// has claimed. That is deliberate: the claims keyspace is GLOBAL (the key is
// the cross-account uniqueness gate), so distinguishing "someone else holds
// this" from "unclaimed" would turn this door into an existence oracle over
// every hostname in the deployment. AttachClaim already refuses in the same
// neutral way, and this must not be the door that leaks what that one
// protects.
func (s *Server) handleAPIDomainGet(w http.ResponseWriter, r *http.Request) {
	_, acct, app, ok := s.instanceGate(w, r)
	if !ok {
		return
	}
	// An instance catch-all answers with its own row and the names it
	// derives, the list door's rows for it. Same 404 for a catch-all this
	// app does not hold as for one nobody does.
	if parent, ok := domains.ParseInstanceCatchallHost(r.PathValue("host")); ok {
		ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
		defer cancel()
		claims, err := s.claims.List(ctx, s.cfg.Releases)
		if err != nil {
			log.Printf("console: api domain get %s/%s *.%s: %v", acct.Sqid, app, parent, err)
			jsonError(w, http.StatusBadGateway, "could not read the hostname")
			return
		}
		host := domains.InstanceCatchallHost(parent)
		claimed := make(map[string]bool, len(claims))
		var mine *domains.Claim
		for i, c := range claims {
			claimed[c.Host] = true
			if c.Host == host && c.Account == acct.Sqid && c.App == app && c.Instances {
				mine = &claims[i]
			}
		}
		if mine == nil {
			jsonError(w, http.StatusNotFound, "no such hostname")
			return
		}
		now := time.Now()
		items := s.catchallListItems(ctx, acct, app, *mine, claimed, aliasReadings(ctx, s.cfg.Releases, now),
			warmRecords(ctx, s.cfg.Releases), s.dnsTargets(), now)
		writeJSON(w, http.StatusOK, map[string]any{
			"domain": items[0], "derived": items[1:],
			"deployment": s.domainCapability(ctx, acct.Sqid, app), "paths": map[string]string{},
		})
		return
	}
	// Shape-checked BEFORE the key builder, exactly as the detach door does:
	// a {host} segment arrives percent-decoded, so "..%2f..%2finstances.json"
	// would reach ClaimKey as a path with separators in it. There is no path
	// through this handler on which an unnormalized host reaches the store.
	host, ok := domains.NormalizeAliasHost(r.PathValue("host"))
	if !ok {
		jsonError(w, http.StatusBadRequest, "invalid hostname")
		return
	}
	ctx, cancel := context.WithTimeout(r.Context(), instanceStoreTimeout)
	defer cancel()
	c, err := domains.GetClaim(ctx, s.cfg.Releases, host)
	// An ABSENT claim is not an error here, and collapsing it into the same
	// 404 the wrong-owner case gets is the whole isolation property. Left as
	// a 502, "nobody has claimed this" would be distinguishable from
	// "somebody else holds it" — which is precisely the existence oracle the
	// neutral 404 exists to prevent. Only a real read failure is a 502.
	if err != nil && !errors.Is(err, os.ErrNotExist) {
		log.Printf("console: api domain get %s/%s %s: %v", acct.Sqid, app, host, err)
		jsonError(w, http.StatusBadGateway, "could not read the hostname")
		return
	}
	if err != nil || c == nil || c.Account != acct.Sqid || c.App != app {
		jsonError(w, http.StatusNotFound, "no such hostname")
		return
	}
	now := time.Now()
	writeJSON(w, http.StatusOK, map[string]any{
		"domain": s.domainItem(ctx, *c, aliasReadings(ctx, s.cfg.Releases, now),
			warmRecord(ctx, s.cfg.Releases, c.Host), s.dnsTargets(), now,
			c.Wildcard && s.delegationZone != ""),
		"deployment": s.domainCapability(ctx, acct.Sqid, app),
		// The prefix map as PUBLISHED, and this is the only surface that
		// answers for it. `carlos routes` shows the route_paths rows the
		// reconcile pass derived, which is ACTUAL state on one box — the pass
		// silently drops an entry whose target is not a same-account local
		// route, so an entry it refused appears on no other surface at all.
		// That is exactly the state an operator debugs, and a migration whose
		// refusals are invisible fails silently.
		//
		// A sibling key rather than a field on domainItem, deliberately: the
		// list door shares that struct, and a host at MaxPathsPerClaim would
		// put 10,000 entries into every row of `carlos domains list`. The
		// whole map belongs on the door that already narrows to one hostname.
		//
		// Always an object, never null: an absent map and an empty one are one
		// state (Claim.Paths is omitempty), and a client should not have to
		// tell a nil from a {} to loop over it.
		"paths": pathsOrEmpty(c.Paths),
	})
}

// domainListCNAMELookupCap bounds how many live CNAME lookups one
// `carlos domains list` call may perform (IMPORTANT-2, Task 5 review): the
// stamp is a real DNS round trip per wildcard-enabled hostname, sequential
// and on the request path, so an unbounded loop turns a listing into a
// resolver-latency multiplier. Claims beyond the cap (in host-sorted order)
// list with delegation_status simply omitted, exactly like an unset zone —
// never an error, never a partial/misleading stamp.
const domainListCNAMELookupCap = 8

// aliasReadings builds a hostname -> reading map from every NON-STALE box's
// own private Metrics.Aliases (status/boxes/*.json), through status.LoadBoxes
// — the same loader and the same staleness rule stagedVersions uses
// (apiinstances.go), for the same reason: a box that stopped reporting is
// EXCLUDED entirely rather than contributing its last-known reading, so a
// hostname whose only box went dark reads "pending" instead of going on
// claiming a cert expiry nobody has checked in a week. now is passed in, not
// read internally, so one request votes on staleness with one clock.
//
// Best-effort throughout: a store that cannot be listed degrades to "nothing
// known" — every claim then lists as pending — rather than failing the call.
// This join is observability on top of the listing, never load-bearing for
// it. A nil store is not reachable here (instanceGate's 503 comes first), but
// the check is kept for any future caller.
func aliasReadings(ctx context.Context, s release.Store, now time.Time) map[string]status.AliasReading {
	if s == nil {
		return nil
	}
	boxes, err := status.LoadBoxes(ctx, s)
	if err != nil {
		log.Printf("console: api domains: could not load status boxes for hostname readings: %v", err)
		return nil
	}
	readings := map[string]status.AliasReading{}
	for _, b := range boxes {
		if b.Metrics == nil || status.BoxStale(b, now, status.SnapshotPeriod) {
			continue
		}
		for host, reading := range b.Metrics.Aliases {
			// Freshest stamp wins. An alias whose primary is everywhere-class
			// materializes on several boxes, and map iteration order is not a
			// tie-break — without this a box that has stopped stamping can
			// deterministically overwrite a live box's reading with a frozen
			// one. Ties keep the incumbent, so the fold is stable.
			if prior, ok := readings[host]; ok && prior.DNSCheckedAt >= reading.DNSCheckedAt {
				continue
			}
			readings[host] = reading
		}
	}
	return readings
}

// warmRecords folds the issuer's warm-outcome records (#299 §3e) into a
// host-keyed map for the LIST door.
//
// A record exists only while a host is failing, so the cost is one object
// per broken hostname in the deployment — usually none. That is the property
// that makes it safe to fold here at all: the list door already pays one Get
// per claim (#173), and a second per-claim read would have made a bad cost
// worse rather than adding a fact.
//
// Every failure degrades to "no records". They explain a state; they never
// gate one, and a domains list that 502s because a telemetry prefix was
// briefly unreadable would be a worse answer than one that says
// "issuing-cert".
func warmRecords(ctx context.Context, s release.Store) map[string]*certwarm.Record {
	out := map[string]*certwarm.Record{}
	if s == nil {
		return out
	}
	keys, err := s.List(ctx, certwarm.Prefix)
	if err != nil {
		log.Printf("console: api domains: could not list %s: %v — certificate failures will read as in progress", certwarm.Prefix, err)
		return out
	}
	for _, key := range keys {
		host := certwarm.HostFromKey(key)
		if host == "" {
			continue
		}
		body, _, err := s.Get(ctx, key)
		if err != nil {
			log.Printf("console: api domains: could not read %s: %v", key, err)
			continue
		}
		rec, err := certwarm.Parse(body)
		if err != nil {
			// A record a NEWER issuer wrote in a shape this console cannot
			// read. Skipping it reports "issuing-cert", which is the right
			// direction to be wrong in.
			log.Printf("console: api domains: could not parse %s: %v", key, err)
			continue
		}
		out[host] = &rec
	}
	return out
}

// warmRecord reads ONE hostname's record, for the per-host door.
//
// Deliberately not warmRecords filtered afterwards: the per-host door's
// whole reason to exist is that a refresh of one hostname costs one object,
// and listing a prefix to answer about a single name would give that back.
// An absent record is the ordinary case and is not an error.
func warmRecord(ctx context.Context, s release.Store, host string) *certwarm.Record {
	if s == nil {
		return nil
	}
	body, _, err := s.Get(ctx, certwarm.Key(host))
	if err != nil {
		if !errors.Is(err, os.ErrNotExist) {
			log.Printf("console: api domains: could not read the warm record for %s: %v", host, err)
		}
		return nil
	}
	rec, err := certwarm.Parse(body)
	if err != nil {
		log.Printf("console: api domains: could not parse the warm record for %s: %v", host, err)
		return nil
	}
	return &rec
}

// hostUnavailableMsg is the ONE refusal string behind every "you cannot have
// this hostname" answer this package gives: the claim already belongs to
// someone else, or a live box in this deployment already serves it as a real
// route. Both reasons answer 409 with these exact bytes and nothing else.
//
// It is a constant rather than three literals because the neutrality is the
// security property. The moment two of these refusals differ — a different
// status, a different message, even different whitespace — a caller can
// binary-search the deployment's hostnames: attach, read the shape of the
// no, learn whether an operator-minted route exists for a name it does not
// own. domains.ErrHostUnavailable carries the same string for the same
// reason (claims.go).
const hostUnavailableMsg = "hostname unavailable"

// deploymentRouteTaken reports whether host is a REAL route — a non-alias
// home entry — published by some live box in this deployment, and therefore
// not this caller's to claim.
//
// Why the door needs this at all. An account can name any hostname it likes;
// the claim's bucket key is the cross-account gate, so a name nobody has
// CLAIMED is free even when a box is already serving it as an operator- or
// reconciler-minted route. Those rows carry no provision record, so the door
// has never been able to see them: it deliberately does not verify that a
// route exists. Until aliases were published fleet-wide that was inert —
// a claim on another box's route materialized only on the claimant's own
// box, which did not serve the name. It is not inert now.
//
// A host this app ALREADY holds the claim on is its own and is allowed
// through. That is not a softening of the rule, it is what makes the rule
// survive contact with the first-route attach: such an attach materializes
// the host as a real route on the claimant's own box, so from the second
// call onward the fold reports the caller's own route back at them. Without
// this, every re-attach would 409 — and titogo's router re-attaches every
// hostname on each reload pass, so the steady state would be a permanent
// refusal on hostnames this deployment itself granted.
//
// Best-effort, like the fold under it: an unreadable bucket answers "no
// conflict", and the box-side reconcile pass stays the authoritative gate.
// An unreadable CLAIM is likewise treated as "not ours" — the conservative
// direction here is to refuse, and the caller who genuinely owns it loses
// nothing but a retry.
func (s *Server) deploymentRouteTaken(ctx context.Context, host, sqid, app string) bool {
	if !edgesfile.DeploymentRoutes(ctx, s.cfg.Releases, time.Now())[host] {
		return false
	}
	c, err := domains.GetClaim(ctx, s.cfg.Releases, host)
	if err == nil && c != nil && c.Account == sqid && c.App == app {
		return false
	}
	return true
}