package main

import (
	"context"
	"crypto/ed25519"
	"crypto/rand"
	"crypto/sha256"
	"database/sql"
	"embed"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"errors"
	"flag"
	"fmt"
	"html"
	"io"
	"io/fs"
	"log"
	"net"
	"net/http"
	"net/url"
	"os"
	"os/signal"
	"strconv"
	"strings"
	"sync"
	"syscall"
	"time"
	"unicode/utf8"

	"lchat/internal/apns"
)

// defaultMaxUploadBytes caps an encrypted attachment upload when
// LCHAT_MAX_UPLOAD_BYTES is unset: ~50 MB, enough for a short Signal-style video
// clip plus AES-GCM overhead. The blob is opaque ciphertext — the server can't
// tell a video from a document.
const defaultMaxUploadBytes = 50 << 20

// defaultBlobQuotaBytes caps total stored blob bytes per instance when
// LCHAT_BLOB_QUOTA_BYTES is unset — the disk backstop. Uploads past it are
// refused (507). Blobs are GC'd on message/thread delete, so this bounds
// worst-case media growth rather than being a hard forever-ceiling.
const defaultBlobQuotaBytes = 2 << 30

// maxServerAvatarBytes caps the admin-set instance branding photo. It's tiny by
// design (the admin console downscales it to ~400px first), so a small cap is
// plenty and keeps this plaintext asset from being abused as bulk storage.
const maxServerAvatarBytes = 1 << 20

//go:embed web/pages/*.html web/static/*
var webFS embed.FS

// The changelog ships inside the binary: one short, user-facing entry per file,
// named <date>-<slug>.md so filename order is announcement order. The deploy
// announcer bot (agent/announcer.mjs) polls /api/changelog and posts entries it
// hasn't seen — "what just shipped" needs no external service, no repo
// credential, and no operator machine: it travels with the deploy itself.
//
//go:embed changelog/*.md
var changelogFS embed.FS

// The mini-app authoring guide also ships inside the binary, served as plain
// markdown at /api/app-guide — so a member can point any LLM at that URL and
// have it learn how to build an app for this instance, with no repo checkout.
// The static checker the guide's delivery step points at rides along the same
// way (GET /api/check-app.mjs), so an author without the repo can still run it.
//
//go:embed docs/building-apps.md docs/building-member-apps.md tools/check-app.mjs
var appGuideFS embed.FS

type Server struct {
	db        *DB
	hub       *Hub
	pages     map[string][]byte
	changelog []ChangelogEntry
	version   string // frontend build hash; clients reload when it changes (see frontendVersion)
	// Where the welcome page's "Get the app" button points (TestFlight / App
	// Store link). Empty hides the button — set LCHAT_APP_STORE_URL per instance.
	appStoreURL string
	// The home server that hosts passkey backup enrolment. The chat page opens
	// <homeOrigin>/enroll as a user-initiated popup to back this instance up (see
	// the enrolment cross-origin contract); set LCHAT_HOME_ORIGIN per deployment.
	homeOrigin string
	// The public-web fetch service this instance's clients should prefer for
	// unfurls (docs/fetch.md) — an origin like https://fetch.example, set via
	// LCHAT_FETCH_URL. Empty (the default, and the self-host default on
	// purpose) keeps unfurling on this instance's own /api/unfurl.
	fetchURL string
	// The cloud ledger's plan flag, mirrored into this instance's env by the
	// provisioner (LCHAT_ENTITLEMENT, "free"/"paid"/"demo"). Gates the space
	// menu's Upgrade entry (free) and the demo countdown band (demo); empty on
	// self-hosted/operator instances, which have no billing surface and show
	// nothing. Display only — a claim flips the ledger without restarting this
	// process, so the band verifies against home's live status before showing.
	entitlement string
	// Where this instance's webhook-ingest sidecar is reachable from outside
	// (LCHAT_HOOKS_BASE, e.g. "http://127.0.0.1:8090" in dev). Empty — the
	// production default — lets clients derive https://in.<host>; set only
	// where that derivation is wrong (local dev, unusual fronting). Served as
	// ingest_base on GET /api/hooks/service; see hooks.go / docs/webhooks.md.
	hooksBase string
	vapidPub  string
	vapidPriv string
	apns      apnsSender // nil unless APNs (direct p8 or relay) is configured
	maxUpload int64      // per-upload attachment cap (LCHAT_MAX_UPLOAD_BYTES)
	blobQuota int64      // per-instance total blob-bytes ceiling (LCHAT_BLOB_QUOTA_BYTES)
	// blobMirrorKick nudges the blob mirror sweep after an upload
	// (blobmirror.go, #992). Nil unless the store is mirrored.
	blobMirrorKick chan struct{}
	// The usage-pipe relay (usage.go, #857): where sidecar usage reports go
	// and the per-space meter token that authenticates them. Pushed into the
	// env by the provisioner; empty = unmetered (self-hosted / BYO key).
	meterURL   string // LCHAT_METER_URL
	meterToken string // LCHAT_METER_TOKEN
	// Directory of sideloaded mini-app modules served at /static/apps-custom/
	// (LCHAT_APPS_DIR); empty disables the feature. See customapps.go.
	appsDir string
	// brakes are the content-blind moderation rate limits (ratelimit.go);
	// lazily nil-safe via s.brake() so tests constructing Server{} literals
	// keep working.
	brakes *modBrakes
	// The report-notification throttle (issue #578): one push per quiet
	// window however many reports land. In-memory on purpose — a restart at
	// worst re-notifies once, and the queue itself is the durable record.
	reportPushMu   sync.Mutex
	lastReportPush time.Time
	// inflight coalesces concurrent unfurls of the same URL+language: one
	// fetch runs, the rest wait on its *previewFlight for the shared result.
	inflight sync.Map
	// active tracks the last time each device token reported being open + focused
	// (token -> unix seconds); activeUsers rolls that up per owner (user id -> unix
	// seconds) so a new message skips push to ALL of a person's devices when they're
	// reading on any one of them — not just the exact device they're on.
	active      sync.Map
	activeUsers sync.Map
	// presence tracks open sockets + last broadcast state per user, so members
	// see who's online/away/offline (presence.go).
	presence presenceTracker
	// upd caches the last verified release-manifest fetch, so the admin console
	// can say whether the tracked channel has something newer (updatecheck.go).
	upd updateState
	// pay is the payment provider for paid access levels (subscriptions.go).
	// noPay unless Stripe Connect is configured — the feature is dormant then.
	pay PayProvider
	// subFold serializes subscription-event folds: the ordering decision
	// (read the watermark, then write the row) spans separate statements,
	// and webhooks arrive concurrently.
	subFold sync.Mutex
	// Tamper evidence (checkpoint.go): the per-instance checkpoint signing key.
	// Empty ckptKeyPath (the default) stores the seed in the DB config so it
	// rides restores; LCHAT_CHECKPOINT_KEY_FILE overrides to a file. ckptMu
	// guards lazy loading (success-only caching); ckptSweepMu serializes the
	// checkpoint sweep so the chain can't fork.
	ckptKeyPath string
	ckptMu      sync.Mutex
	ckptKey     ed25519.PrivateKey
	ckptSweepMu sync.Mutex
}

func main() {
	// Subcommands: `lchat router` runs the multi-instance front door and the
	// add-instance/instances/admin-link commands manage it; anything else (bare
	// `lchat` plus all existing flags) runs a single instance, so existing
	// invocations are unchanged. See docs/instance-router.md.
	if len(os.Args) > 1 {
		switch os.Args[1] {
		case "router":
			runRouter(os.Args[2:])
			return
		case "bootstrap":
			runBootstrap(os.Args[2:])
			return
		case "add-instance":
			runAddInstance(os.Args[2:])
			return
		case "mesh-seed":
			runMeshSeed(os.Args[2:])
			return
		case "deploy":
			runDeploy(os.Args[2:])
			return
		case "add-service":
			runAddService(os.Args[2:])
			return
		case "add-bot":
			runAddBot(os.Args[2:])
			return
		case "bot":
			runBotCmd(os.Args[2:])
			return
		case "agents":
			runAgentsCmd(os.Args[2:])
			return
		case "add-hooks":
			runAddHooks(os.Args[2:])
			return
		case "hooks":
			runHooksCmd(os.Args[2:])
			return
		case "links":
			runLinksCmd(os.Args[2:])
			return
		case "fetch":
			runFetchCmd(os.Args[2:])
			return
		case "remove":
			runRemove(os.Args[2:])
			return
		case "instances":
			runInstances(os.Args[2:])
			return
		case "env":
			runEnvCmd(os.Args[2:])
			return
		case "hibernate":
			runHibernate(os.Args[2:])
			return
		case "canary":
			runCanary(os.Args[2:])
			return
		case "reset":
			runReset(os.Args[2:])
			return
		case "replication":
			runReplication(os.Args[2:])
			return
		case "relocate":
			runRelocate(os.Args[2:])
			return
		case "admin-link":
			runAdminLink(os.Args[2:])
			return
		case "setup-invite":
			runSetupInvite(os.Args[2:])
			return
		case "version":
			// The build id compiled in via -ldflags "-X main.buildVersion=<id>".
			// `stage` reads it from a built binary; the running instance reports it
			// at /api/version so a deploy can confirm the swap actually took.
			fmt.Println(buildVersion)
			return
		case "stage":
			runStage(os.Args[2:])
			return
		case "install":
			runInstall(os.Args[2:])
			return
		case "rollback":
			runRollback(os.Args[2:])
			return
		case "init-versions":
			runInitVersions(os.Args[2:])
			return
		case "release":
			runRelease(os.Args[2:])
			return
		case "update":
			runUpdate(os.Args[2:])
			return
		case "controld":
			runControld(os.Args[2:])
			return
		case "cloud":
			runCloud(os.Args[2:])
			return
		case "try":
			runTryCmd(os.Args[2:])
			return
		case "relay":
			runRelayCmd(os.Args[2:])
			return
		case "tunnel":
			runTunnelCmd(os.Args[2:])
			return
		}
		// No case matched. A flag falls through to the single-instance form
		// below (unchanged); a word does not — it is a typo, and starting a
		// server for it is how a stray `lchat help` ran for days on a live
		// box. See subcommands.go.
		checkSubcommand(os.Args[1])
	}

	addr := flag.String("addr", envOr("ADDR", ":1747"), "listen address (env: ADDR)")
	socket := flag.String("socket", envOr("LCHAT_SOCKET", ""), "unix socket to serve on instead of -addr (env: LCHAT_SOCKET); how the router fronts an instance")
	dbPath := flag.String("db", envOr("LCHAT_DB", "lchat.db"), "path to SQLite database file (env: LCHAT_DB)")
	resetAdmin := flag.Bool("reset-admin", false, "generate a new admin token and print its link")
	resetDB := flag.Bool("reset-db", false, "delete and recreate the database")
	flag.Parse()

	if *resetDB {
		_ = os.Remove(*dbPath)
		log.Printf("database reset: %s deleted", *dbPath)
	}

	db, err := openDB(*dbPath)
	if err != nil {
		log.Fatalf("open db: %v", err)
	}

	// Admin token: LCHAT_ADMIN_TOKEN env wins; otherwise generate one on first run.
	// NB: LCHAT_-prefixed on purpose — some platforms (e.g. Miren) auto-provision
	// a secret for a bare "ADMIN_TOKEN" and silently override your value.
	// TrimSpace guards against env-injection paths that add surrounding whitespace.
	if tok, err := db.ensureAdminToken(strings.TrimSpace(os.Getenv("LCHAT_ADMIN_TOKEN"))); err != nil {
		log.Fatalf("admin token: %v", err)
	} else if tok != "" {
		printAdminLink(*addr, tok)
	}
	if *resetAdmin {
		tok, err := db.resetAdminToken()
		if err != nil {
			log.Fatalf("reset admin token: %v", err)
		}
		printAdminLink(*addr, tok)
	}
	if err := applySeededName(db); err != nil {
		log.Fatalf("seeded name: %v", err)
	}
	if err := applySkipSetup(db); err != nil {
		log.Fatalf("skip-setup defaults: %v", err)
	}

	pages, err := loadPages()
	if err != nil {
		log.Fatalf("load pages: %v", err)
	}
	hub := newHub()
	go hub.run()
	// TrimSpace guards against env-injection paths that add surrounding whitespace;
	// fall back to the shared home server when unset.
	homeOrigin := strings.TrimSpace(os.Getenv("LCHAT_HOME_ORIGIN"))
	if homeOrigin == "" {
		homeOrigin = defaultHomeOrigin
	}
	s := &Server{db: db, hub: hub, pages: pages, changelog: loadChangelog(), version: frontendVersion(),
		appStoreURL: strings.TrimSpace(os.Getenv("LCHAT_APP_STORE_URL")), homeOrigin: homeOrigin,
		fetchURL:     strings.TrimRight(strings.TrimSpace(os.Getenv("LCHAT_FETCH_URL")), "/"),
		entitlement: strings.TrimSpace(os.Getenv("LCHAT_ENTITLEMENT")),
		maxUpload:   envBytes("LCHAT_MAX_UPLOAD_BYTES", defaultMaxUploadBytes),
		blobQuota:   envBytes("LCHAT_BLOB_QUOTA_BYTES", defaultBlobQuotaBytes),
		meterURL:    strings.TrimSpace(os.Getenv("LCHAT_METER_URL")),
		meterToken:  strings.TrimSpace(os.Getenv("LCHAT_METER_TOKEN")),
		hooksBase:   strings.TrimRight(strings.TrimSpace(os.Getenv("LCHAT_HOOKS_BASE")), "/"),
		appsDir:     strings.TrimSpace(os.Getenv("LCHAT_APPS_DIR"))}
	s.brakes = newModBrakes()

	// Tamper evidence (checkpoint.go): by default the signing seed lives in
	// the DB config so it survives hibernation wakes and migrations; set
	// LCHAT_CHECKPOINT_KEY_FILE to keep it in a file outside the DB instead.
	s.ckptKeyPath = strings.TrimSpace(os.Getenv("LCHAT_CHECKPOINT_KEY_FILE"))

	// Web Push: self-generated VAPID keypair (no third-party account).
	if pub, priv, err := db.ensureVAPID(); err != nil {
		log.Fatalf("vapid: %v", err)
	} else {
		s.vapidPub, s.vapidPriv = pub, priv
	}
	s.apns = newAPNsClient()

	// Paid access levels (subscriptions.go): the Stripe Connect provider, or
	// noPay (dormant) when unconfigured. The grace→revoke sweep only matters
	// once entitlements exist; harmless to always run.
	s.pay = newPayProvider(db)
	s.startBillingSweep()

	// Mini-app scheduling: deliver due "future messages" (miniapps.go). Tests
	// call sweepDueScheduled directly, so only the real server runs the ticker.
	go s.runScheduler()
	go s.runUpdateChecker()
	// Presence idle sweep (presence.go). Tests call sweepPresence directly.
	go s.runPresenceSweeper()
	// Blob mirror + audit sweeps (blobmirror.go, #992). No-op unless the
	// store is mirrored; tests call mirrorOnce/auditBlobsOnce directly.
	s.startBlobMirror()
	// Tamper evidence: fold new journal rows into signed checkpoints
	// (checkpoint.go). Tests call sweepCheckpoint directly.
	go s.runCheckpointer()
	// Push release notes new in THIS binary to the admins (announce.go). Tests
	// call announceChangelog directly.
	go s.announceChangelog()

	ln, where, err := listen(*addr, *socket)
	if err != nil {
		log.Fatalf("listen: %v", err)
	}
	log.Printf("lchat listening on %s (db: %s)", where, *dbPath)

	// ReadHeaderTimeout caps how long a client may dribble request headers
	// (Slowloris): standalone self-hosts bind this listener straight to public
	// TCP. Same 10s the router/cloud/controld listeners use.
	srv := &http.Server{Handler: s.handler(), ReadHeaderTimeout: 10 * time.Second}
	go func() {
		if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
			log.Fatalf("serve: %v", err)
		}
	}()

	// Graceful shutdown on SIGTERM/SIGINT (systemd stop/restart during a deploy):
	// stop accepting + drain in-flight HTTP, then close WebSockets so clients
	// reconnect to the new process. The router retries dials across the brief gap,
	// so no request is dropped. See docs/instance-router.md.
	sigCh := make(chan os.Signal, 1)
	signal.Notify(sigCh, syscall.SIGTERM, syscall.SIGINT)
	<-sigCh
	log.Printf("lchat: draining and shutting down")
	// Drain in-flight HTTP (e.g. a large upload) before exiting. Kept below the
	// router's dial-retry window so the socket-absent gap during a deploy stays
	// within what the router masks.
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	_ = srv.Shutdown(ctx)
	hub.shutdown()
}

// listen returns the instance's listener. With -socket set it serves on a unix
// domain socket (how the router fronts an instance — see docs/instance-router.md);
// otherwise it's a TCP listener on addr (the standalone default, unchanged). A
// stale socket left by a crashed process is removed first (but a socket another
// process is still serving on refuses to start), and the socket is chmod 0600 so
// only the router (same user) can dial it.
func listen(addr, socketPath string) (net.Listener, string, error) {
	if socketPath == "" {
		ln, err := net.Listen("tcp", addr)
		return ln, addr, err
	}
	// Don't clobber a live socket: only a stale one (nothing listening) is removed.
	if c, err := net.DialTimeout("unix", socketPath, 200*time.Millisecond); err == nil {
		c.Close()
		return nil, "", fmt.Errorf("socket %s is already in use by another process", socketPath)
	}
	if err := os.Remove(socketPath); err != nil && !os.IsNotExist(err) {
		return nil, "", fmt.Errorf("remove stale socket %s: %w", socketPath, err)
	}
	ln, err := net.Listen("unix", socketPath)
	if err != nil {
		return nil, "", err
	}
	if err := os.Chmod(socketPath, 0o600); err != nil {
		ln.Close()
		return nil, "", fmt.Errorf("chmod socket %s: %w", socketPath, err)
	}
	return ln, "unix:" + socketPath, nil
}

// handler wires up all routes. It's a method so tests can exercise the full
// router via httptest without starting a real listener.
func (s *Server) handler() http.Handler {
	// The moderation brakes (ratelimit.go) exist before the first request —
	// handler() is the one door every construction path (main, tests) passes
	// through, so the lazy s.brake() fallback never races concurrent handlers.
	if s.brakes == nil {
		s.brakes = newModBrakes()
	}
	staticFS, err := fs.Sub(webFS, "web/static")
	if err != nil {
		log.Fatalf("static fs: %v", err)
	}

	mux := http.NewServeMux()
	// Pages
	mux.HandleFunc("GET /", s.servePage("index.html"))
	mux.HandleFunc("GET /admin", s.servePage("admin.html"))
	mux.HandleFunc("GET /join/{token}", s.servePage("join.html"))
	mux.Handle("GET /static/", noCache(http.StripPrefix("/static/", http.FileServer(http.FS(staticFS)))))
	// Custom (sideloaded) mini-apps. Deliberately one segment below /static/ so a
	// custom app's relative `import "../apps.js"` resolves to /static/apps.js —
	// same imports as a compiled-in app. See customapps.go for the trust model.
	mux.Handle("GET /static/apps-custom/{name}", noCache(http.HandlerFunc(s.serveCustomApp)))
	mux.HandleFunc("GET /api/apps", s.getCustomApps)
	// The integrations registry (public, like /api/apps): which services can
	// be connected and exactly what each op may do. See integrations_api.go.
	mux.HandleFunc("GET /api/integrations", s.getIntegrations)
	// Installing/removing custom apps is admin-only, like the rest of /api/admin.
	mux.HandleFunc("GET /api/admin/apps", s.listCustomAppsHandler)
	mux.HandleFunc("PUT /api/admin/apps/{name}", s.putCustomAppHandler)
	mux.HandleFunc("DELETE /api/admin/apps/{name}", s.deleteCustomAppHandler)
	// Member-built apps (memberapps.go): instance-key-encrypted blobs the client
	// runs only inside the sandbox frame below. Deploying is member-gated.
	mux.HandleFunc("GET /api/member-apps", s.listMemberAppsHandler)
	mux.HandleFunc("GET /api/member-apps/{id}/versions", s.memberAppVersionsHandler)
	mux.HandleFunc("PUT /api/member-apps/{id}", s.putMemberAppHandler)
	mux.HandleFunc("DELETE /api/member-apps/{id}", s.deleteMemberAppHandler)
	// Member bots (memberbots.go): opaque charter blobs, stored like member
	// apps; the sidecar decrypts and runs them (docs/member-bots.md).
	mux.HandleFunc("GET /api/member-bots", s.listMemberBotsHandler)
	mux.HandleFunc("PUT /api/member-bots/{id}", s.putMemberBotHandler)
	mux.HandleFunc("DELETE /api/member-bots/{id}", s.deleteMemberBotHandler)
	// The charter host's wake-time report (bot-token-gated; folded into
	// GET /api/next-due so hibernated charters still fire on time).
	mux.HandleFunc("POST /api/charter-next-due", s.postCharterNextDue)
	mux.HandleFunc("POST /api/bot-usage", s.postBotUsage)
	// Incoming webhooks (hooks.go, docs/webhooks.md): admin-managed registry of
	// opaque definition blobs the hooks sidecar polls; deployed is the sidecar's
	// plaintext go-live ack.
	mux.HandleFunc("GET /api/hooks/service", s.getHooksService)
	mux.HandleFunc("POST /api/hooks", s.createWebhookHandler)
	mux.HandleFunc("PUT /api/hooks/{id}/blobs", s.putWebhookBlobsHandler)
	mux.HandleFunc("GET /api/hooks", s.listWebhooksHandler)
	mux.HandleFunc("GET /api/hooks/defs", s.listWebhookDefsHandler)
	mux.HandleFunc("POST /api/hooks/{id}/deployed", s.webhookDeployedHandler)
	mux.HandleFunc("DELETE /api/hooks/{id}", s.deleteWebhookHandler)
	// The sandbox frame document: an opaque-origin cage for member-app code.
	mux.HandleFunc("GET /app-sandbox", s.serveAppSandbox)

	// Chat API (transport auth via invite token; never sees plaintext)
	mux.HandleFunc("GET /api/messages", s.getMessages)
	// Tamper evidence: the signed checkpoint chain over the event journal
	// (checkpoint.go; docs/tamper-evidence.md). Member-gated like messages.
	mux.HandleFunc("GET /api/checkpoints", s.getCheckpoints)
	// Merkle inclusion proof that a held message is committed to the chain
	// (checkpoint.go; docs/tamper-evidence.md client sampling). Member-gated.
	mux.HandleFunc("GET /api/checkpoint-proof", s.getCheckpointProof)
	mux.HandleFunc("POST /api/messages", s.postMessage)
	// Message permalinks ("Copy link", issue #893): mint an opaque, server-
	// sealed token for a message; resolve turns it back into ids only for a
	// caller who is currently a thread member (links.go).
	mux.HandleFunc("POST /api/messages/{id}/link", s.mintMessageLink)
	mux.HandleFunc("POST /api/resolve-link", s.resolveMessageLink)
	mux.HandleFunc("GET /ws", s.handleWS)

	// Threads & roster (see docs/threads-and-dms.md). The roster is the open
	// directory; threads (DMs/groups) carry server-blind, per-member wrapped keys.
	mux.HandleFunc("POST /api/pubkey", s.setPubkey)
	mux.HandleFunc("GET /api/roster", s.getRoster)
	mux.HandleFunc("GET /api/bot-config", s.getBotConfig)
	mux.HandleFunc("POST /api/bot-config", s.declareBotKind)
	mux.HandleFunc("GET /api/me", s.getMe)
	mux.HandleFunc("POST /api/device/signout", s.signout)
	mux.HandleFunc("POST /api/apns/subscribe", s.apnsSubscribe)
	mux.HandleFunc("POST /api/apns/unsubscribe", s.apnsUnsubscribe)
	// Instance key + profile photos: a shared key for all-members content (avatars).
	mux.HandleFunc("GET /api/instance-key", s.getInstanceKey)
	mux.HandleFunc("POST /api/instance-key", s.postInstanceKey)

	// The space thread — the hidden all-members thread backing space-wide apps
	// (spacethread.go, docs/space-apps.md).
	mux.HandleFunc("GET /api/space-thread", s.getSpaceThread)
	mux.HandleFunc("POST /api/space-thread", s.postSpaceThread)
	mux.HandleFunc("POST /api/admin/space-thread/reset", s.resetSpaceThreadHandler)
	mux.HandleFunc("POST /api/instance-key/nudge", s.nudgeInstanceKey)
	mux.HandleFunc("POST /api/admin/instance-key/reset", s.resetInstanceKeyHandler)
	// Tiers: admin-curated member sets with their own keys (docs/community-and-tiers.md).
	mux.HandleFunc("GET /api/tiers", s.getTiers)
	mux.HandleFunc("POST /api/tiers", s.postTier)
	mux.HandleFunc("DELETE /api/tiers/{id}", s.deleteTierHandler)
	mux.HandleFunc("POST /api/tiers/{id}/members", s.postTierMember)
	mux.HandleFunc("POST /api/tiers/{id}/remove", s.postTierRemove)
	mux.HandleFunc("POST /api/tiers/{id}/keys", s.postTierKeys)
	mux.HandleFunc("POST /api/tiers/{id}/nudge", s.nudgeTierKey)
	mux.HandleFunc("POST /api/tiers/{id}/policy", s.postTierPolicy)
	mux.HandleFunc("POST /api/tiers/{id}/show", s.postTierShow)
	// Paid access levels (subscriptions.go): admin price + account, member
	// subscribe/change/cancel/portal, and the provider webhook (public — its
	// signature is the auth). Dormant when no provider is configured.
	mux.HandleFunc("POST /api/tiers/{id}/price", s.postTierPrice)
	mux.HandleFunc("POST /api/tiers/{id}/subscribe", s.postTierSubscribe)
	mux.HandleFunc("POST /api/tiers/{id}/change", s.postTierChange)
	mux.HandleFunc("POST /api/tiers/{id}/cancel-subscription", s.postTierCancelSub)
	mux.HandleFunc("POST /api/tiers/{id}/resume", s.postTierResume)
	mux.HandleFunc("POST /api/tiers/{id}/portal", s.postTierPortal)
	mux.HandleFunc("POST /api/admin/billing/account", s.postBillingAccount)
	mux.HandleFunc("GET /api/admin/billing", s.getBillingStatus)
	mux.HandleFunc("POST /api/billing/webhook", s.stripeConnectWebhook)
	mux.HandleFunc("POST /api/label", s.postLabel)
	mux.HandleFunc("POST /api/label/backfill", s.postLabelBackfill)
	mux.HandleFunc("POST /api/presence", s.postPresence)
	mux.HandleFunc("POST /api/avatar", s.postAvatar)
	mux.HandleFunc("POST /api/description", s.postDescription)
	mux.HandleFunc("GET /api/nicknames", s.getNicknames)
	mux.HandleFunc("POST /api/nicknames", s.postNicknames)
	mux.HandleFunc("GET /api/prefs", s.getPrefs)
	mux.HandleFunc("POST /api/prefs", s.postPrefs)
	mux.HandleFunc("POST /api/dm-privacy", s.postDMPrivacy)
	mux.HandleFunc("GET /api/blocks", s.getBlocks)
	mux.HandleFunc("POST /api/blocks", s.postBlock)
	mux.HandleFunc("DELETE /api/blocks/{id}", s.deleteBlock)
	mux.HandleFunc("POST /api/reports", s.postReport)
	mux.HandleFunc("GET /api/admin/reports", s.adminReports)
	mux.HandleFunc("POST /api/admin/reports/{id}/resolve", s.resolveReportHandler)
	mux.HandleFunc("POST /api/admin/warn", s.adminWarn)
	mux.HandleFunc("GET /api/admin/audit", s.adminAudit)
	mux.HandleFunc("POST /api/admin/users/{id}/ban", s.banUser)
	mux.HandleFunc("POST /api/group-description", s.postGroupDescription)
	mux.HandleFunc("GET /api/threads", s.getThreads)
	mux.HandleFunc("POST /api/threads", s.postThread)
	mux.HandleFunc("GET /api/threads/open", s.getOpenThreads)
	mux.HandleFunc("POST /api/threads/{id}/join", s.postThreadJoin)
	mux.HandleFunc("POST /api/threads/{id}/visibility", s.postThreadVisibility)
	mux.HandleFunc("POST /api/threads/{id}/default", s.postThreadDefault)
	mux.HandleFunc("POST /api/threads/{id}/members", s.postThreadMember)
	mux.HandleFunc("POST /api/threads/{id}/name", s.postThreadName)
	mux.HandleFunc("POST /api/threads/{id}/avatar", s.postThreadAvatar)
	mux.HandleFunc("POST /api/threads/{id}/leave", s.postThreadLeave)
	mux.HandleFunc("POST /api/threads/{id}/cancel-invite", s.cancelInvite)
	mux.HandleFunc("POST /api/threads/{id}/remove", s.postThreadRemove)
	mux.HandleFunc("POST /api/threads/{id}/hidden", s.postThreadHidden)
	mux.HandleFunc("POST /api/threads/{id}/pinned", s.postThreadPinned)
	mux.HandleFunc("POST /api/threads/{id}/muted", s.postThreadMuted)
	mux.HandleFunc("POST /api/threads/{id}/close-dm", s.postCloseDM)
	mux.HandleFunc("POST /api/threads/{id}/reopen-dm", s.postReopenDM)
	mux.HandleFunc("POST /api/threads/{id}/read", s.postThreadRead)

	// Mini-apps (miniapps.go): scheduled "future messages" + per-thread state
	// snapshots. Both carry only client-encrypted blobs; both are member-gated.
	mux.HandleFunc("POST /api/schedule", s.postSchedule)
	mux.HandleFunc("GET /api/schedule", s.getSchedules)
	mux.HandleFunc("DELETE /api/schedule/{id}", s.deleteSchedule)
	// The activator's due-time probe (admin-gated; queried over the instance
	// socket at sleep time so hibernated schedules still fire on time).
	mux.HandleFunc("GET /api/next-due", s.getNextDue)
	mux.HandleFunc("GET /api/threads/{id}/state", s.getThreadStateHandler)
	mux.HandleFunc("PUT /api/threads/{id}/state", s.putThreadStateHandler)

	// Connected third-party services (docs/connected-services.md): opaque,
	// client-encrypted credential blobs keyed per member. Token-gated; the server
	// never reads inside.
	mux.HandleFunc("GET /api/connected", s.listConnected)
	mux.HandleFunc("GET /api/connected/{service}", s.getConnected)
	mux.HandleFunc("PUT /api/connected/{service}", s.putConnected)
	mux.HandleFunc("DELETE /api/connected/{service}", s.deleteConnected)
	// OAuth connect (docs/connected-services.md): public config for the browser to
	// start a PKCE flow, and the redirect landing that relays the code back.
	mux.HandleFunc("GET /api/oauth/config", s.oauthConfig)
	mux.HandleFunc("GET /oauth/{service}/callback", s.oauthCallbackPage)

	// Encrypted attachments: bytes are E2E-encrypted in the browser; the server
	// stores/serves opaque blobs only. Both ends are token-gated.
	mux.HandleFunc("POST /api/upload", s.uploadBlob)
	mux.HandleFunc("GET /api/blob/{id}", s.getBlobHandler)

	// Link previews: the server fetches a posted URL to build an OpenGraph card,
	// caches it, and serves cached results immediately (refreshing stale ones).
	mux.HandleFunc("GET /api/unfurl", s.unfurl)

	// Key-invites (invite redesign): server stores a client-wrapped key it can't
	// open; claiming mints a device token. See docs/invite-redesign.md.
	mux.HandleFunc("GET /api/key-invite/{id}", s.getKeyInvite)
	mux.HandleFunc("POST /api/key-invite/{id}/claim", s.claimKeyInvite)
	mux.HandleFunc("POST /api/key-invite/{id}/adopt", s.adoptKeyInvite)
	mux.HandleFunc("POST /api/admin/key-invites", s.createKeyInvite)
	mux.HandleFunc("GET /api/admin/tiers", s.adminTiers)
	mux.HandleFunc("GET /api/admin/users", s.listUsers)
	mux.HandleFunc("POST /api/admin/users/{id}/remove", s.removeUser)
	mux.HandleFunc("POST /api/admin/users/{id}/label", s.renameUser)
	mux.HandleFunc("GET /api/admin/bots/{id}/config", s.getAdminBotConfig)
	mux.HandleFunc("POST /api/admin/bots/{id}/config", s.setAdminBotConfig)
	// A member can mint a fresh invite for their own account (add a device).
	mux.HandleFunc("POST /api/device-invites", s.createDeviceInvite)
	// A member can invite a new person straight into a DM (gated by an admin setting).
	mux.HandleFunc("POST /api/invites", s.postUserInvite)

	// Group name (public read so the page/manifest can show it; admin write)
	mux.HandleFunc("GET /api/group", s.getGroup)
	// Server avatar: per-instance branding photo. Public read (shown in onboarding,
	// the home Save-passkey card, and native add-chat — all before any key exists);
	// admin write/clear. Served in the clear like the group name (see getServerAvatar).
	mux.HandleFunc("GET /api/server-avatar", s.getServerAvatar)
	mux.HandleFunc("POST /api/admin/server-avatar", s.setServerAvatar)
	mux.HandleFunc("DELETE /api/admin/server-avatar", s.deleteServerAvatar)
	// Frontend build version — clients poll this on returning to the app and reload
	// if it changed (auto-update). No auth: it's just a build hash.
	mux.HandleFunc("GET /api/version", s.getVersion)
	mux.HandleFunc("GET /api/update-prefs", s.getUpdatePrefs)
	mux.HandleFunc("GET /api/changelog", s.getChangelog)
	// The mini-app authoring guide. Static documentation compiled into the
	// binary — never instance data — so, like /api/version, it isn't token-gated:
	// the whole point is that an external LLM can be pointed straight at it.
	mux.HandleFunc("GET /api/app-guide", s.getAppGuide)
	mux.HandleFunc("GET /api/member-app-guide", s.getMemberAppGuide)
	mux.HandleFunc("GET /api/check-app.mjs", s.getAppChecker)
	mux.HandleFunc("POST /api/admin/group", s.setGroup)
	// Sealed branding (docs/no-plaintext.md): the client-sealed branding set
	// and its reversal. Admin-gated; the ciphertext is produced client-side.
	mux.HandleFunc("POST /api/admin/branding/seal", s.sealBranding)
	mux.HandleFunc("POST /api/admin/branding/unseal", s.unsealBranding)

	// Admin API (requires admin token)
	mux.HandleFunc("GET /api/admin/settings", s.getSettings)
	mux.HandleFunc("POST /api/admin/settings", s.setSettings)

	// Web Push (VAPID self-generated; pushed payload is ciphertext, decrypted in the SW)
	mux.HandleFunc("GET /api/push/vapid", s.getVAPID)
	mux.HandleFunc("POST /api/push/subscribe", s.subscribePush)
	mux.HandleFunc("POST /api/push/unsubscribe", s.unsubscribePush)
	mux.HandleFunc("POST /api/admin/test-push", s.testPush)

	// PWA: the service worker must be served from the root scope; manifest for install
	mux.HandleFunc("GET /sw.js", s.serveSW)
	mux.HandleFunc("GET /manifest.webmanifest", s.serveManifest)
	// Universal links: lets invite links on this instance's domain open straight
	// into the iOS app when it's installed (every instance is its own domain, and
	// every instance is this same binary, so each serves its own association file).
	mux.HandleFunc("GET /.well-known/apple-app-site-association", serveAASA)

	return securityHeaders(mux)
}

// securityHeaders adds defense-in-depth headers to every response. The page
// Content-Security-Policy needs a per-request nonce, so it's set in servePage;
// these are the static ones that apply everywhere (including the blob download,
// where nosniff stops a mistyped blob being sniffed as HTML).
func securityHeaders(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		h := w.Header()
		h.Set("X-Content-Type-Options", "nosniff")
		h.Set("X-Frame-Options", "DENY")
		h.Set("Referrer-Policy", "no-referrer")
		// Ignored by browsers over plain HTTP (e.g. local dev); applies in prod
		// where every instance is served over TLS.
		h.Set("Strict-Transport-Security", "max-age=31536000")
		next.ServeHTTP(w, r)
	})
}

// cspNonce returns a fresh per-response nonce for the pages' inline <script>
// tags, so the CSP can allow exactly those and reject any injected script.
func cspNonce() string {
	var b [16]byte
	if _, err := rand.Read(b[:]); err != nil {
		return "" // fail closed: no inline script will match an empty nonce
	}
	return base64.StdEncoding.EncodeToString(b[:])
}

// ---- pages --------------------------------------------------------------

func loadPages() (map[string][]byte, error) {
	pages := map[string][]byte{}
	for _, name := range []string{"index.html", "admin.html", "join.html"} {
		b, err := webFS.ReadFile("web/pages/" + name)
		if err != nil {
			return nil, err
		}
		pages[name] = b
	}
	return pages, nil
}

// requestBase reconstructs the external scheme+host (e.g. "https://chat.paulca.com")
// as the browser reached us. The router terminates TLS and proxies over a unix
// socket, so the real scheme rides in X-Forwarded-Proto (SetXForwarded, router.go);
// prod is always TLS, so default to https when unproxied.
func requestBase(r *http.Request) string {
	scheme := "https"
	if xfp := r.Header.Get("X-Forwarded-Proto"); xfp != "" {
		scheme = xfp
	} else if r.TLS == nil {
		scheme = "http"
	}
	return scheme + "://" + r.Host
}

func (s *Server) servePage(name string) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// "GET /" matches everything; only the exact root serves the chat page.
		if name == "index.html" && r.URL.Path != "/" {
			http.NotFound(w, r)
			return
		}
		// A per-request nonce whitelists exactly the pages' own inline <script>
		// blocks, so an injected inline script (the highest-value attack here — it
		// could read the private key out of localStorage) is blocked. Third-party
		// image/frame sources are limited to what the app actually loads (preview
		// images over https, YouTube's no-cookie embed); everything else is 'self'.
		nonce := cspNonce()
		// The fetch service (docs/fetch.md) is one more named connect-src host, present
		// only when this instance opts in — img-src's blanket https: already
		// admits its proxied card images.
		fetchSrc := ""
		if s.fetchURL != "" {
			fetchSrc = " " + s.fetchURL
		}
		w.Header().Set("Content-Security-Policy",
			"default-src 'self'; "+
				"script-src 'self' 'nonce-"+nonce+"'; "+
				"style-src 'self' 'unsafe-inline'; "+
				"img-src 'self' data: blob: https:; "+
				// Video/audio play from client-decrypted blob: URLs (E2E — the server
				// only holds ciphertext), so media-src must allow blob: or the
				// <video> is refused. Without this it falls back to default-src 'self'.
				"media-src 'self' blob:; "+
				// *.giphy.com is the /gif app's CLIENT-side doorway (hostBridge.gif in
				// shell.js): search + GIF download happen in the browser, so the server
				// never sees the query or the pick — the deliberate, disclosed sibling
				// of the unfurl trade-off. The home origin admits exactly one call: the
				// enrolment completion poll (backup.js startEnrolPoll), which sends only
				// the client-random nonce. Keep connect-src pinned to named hosts.
				"connect-src 'self' https://*.giphy.com "+s.homeOrigin+fetchSrc+"; "+
				// 'self' admits exactly one same-origin frame: /app-sandbox, the
				// opaque-origin cage member apps run in (memberapps.go).
				"frame-src 'self' https://www.youtube-nocookie.com; "+
				"object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'")
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
		// Inject the configurable group name (HTML-escaped — it's admin-set) and the
		// build version (so the page knows which frontend it loaded — see /api/version).
		page := strings.ReplaceAll(string(s.pages[name]), "__GROUP_NAME__", html.EscapeString(s.db.getGroupName()))
		page = strings.ReplaceAll(page, "__APP_VERSION__", s.version)
		// Whether ordinary members may invite people (gates the invite UI; the server
		// enforces it regardless). Injected so the client needs no extra round trip.
		page = strings.ReplaceAll(page, "__USER_INVITES__", boolStr(s.db.usersCanInvite()))
		// Per-instance feature gates (same deal: hide the entry points here, the
		// gated endpoints enforce).
		page = strings.ReplaceAll(page, "__ENABLE_AI__", boolStr(s.db.aiEnabled()))
		page = strings.ReplaceAll(page, "__ENABLE_BOTS__", boolStr(s.db.botsEnabled()))
		page = strings.ReplaceAll(page, "__ENABLE_APPS__", boolStr(s.db.appsEnabled()))
		page = strings.ReplaceAll(page, "__ENABLE_MEMBER_APPS__", boolStr(s.db.memberAppsEnabled()))
		// Space-install policy (client-enforced; see db.spaceInstallsAdmins).
		page = strings.ReplaceAll(page, "__SPACE_INSTALLS_ADMINS__", boolStr(s.db.spaceInstallsAdmins()))
		// The welcome page's "Get the app" destination; empty hides the button.
		page = strings.ReplaceAll(page, "__APP_STORE_URL__", html.EscapeString(s.appStoreURL))
		// The home server the chat page enrols into for passkey backup.
		page = strings.ReplaceAll(page, "__HOME_ORIGIN__", html.EscapeString(s.homeOrigin))
		page = strings.ReplaceAll(page, "__FETCH_URL__", html.EscapeString(s.fetchURL))
		// The provisioner-pushed plan flag ("free"/"paid"; empty when self-hosted)
		// — gates the space menu's Upgrade entry, enforced by nothing here: the
		// checkout itself lives on the home server.
		page = strings.ReplaceAll(page, "__ENTITLEMENT__", html.EscapeString(s.entitlement))
		// Link-preview (OpenGraph) fields for the join page. Absolute URLs, since
		// crawlers fetch with no base. The image is the server branding avatar when
		// set, else the app logo — both plaintext branding, never user content, so
		// this leaks nothing beyond what the group name already does.
		if name == "join.html" {
			base := requestBase(r)
			ogImage := base + "/static/icon-512.png"
			// A sealed avatar is ciphertext — crawlers can't render it, so OG
			// cards keep the app logo (the group name is likewise the default).
			if _, mime, _, hasAvatar := s.db.getInstanceAvatar(); hasAvatar && mime != sealedAvatarMime {
				ogImage = base + "/api/server-avatar"
			}
			page = strings.ReplaceAll(page, "__OG_URL__", html.EscapeString(base+r.URL.EscapedPath()))
			page = strings.ReplaceAll(page, "__OG_IMAGE__", html.EscapeString(ogImage))
		}
		page = strings.ReplaceAll(page, "__CSP_NONCE__", nonce)
		w.Write([]byte(page))
	}
}

// The home server that hosts passkey backup enrolment when LCHAT_HOME_ORIGIN is
// unset. See the enrolment cross-origin contract (web/static/backup.js).
const defaultHomeOrigin = "https://home.elevenmessenger.com"

// The apps this deployment's instances associate with (team + bundle ids) —
// public by definition (they ship in every AASA file and in the apps
// themselves). The Mac id is the server half of Mac universal links
// (docs/native-onboarding.md E.1/E.2, issue #1376): inert until the Mac app
// ships its applinks entitlement (E.2), at which point /join links open the
// app directly instead of riding the custom-scheme handoff.
const appleAppID = "J5NDF5PCD8.com.elevenmessenger.messenger"
const appleMacAppID = "J5NDF5PCD8.com.elevenmessenger.messenger.mac"

// serveAASA answers Apple's app-site-association probe. Apple's CDN fetches it
// when the app installs/updates; matching /join/* links then open in the app
// instead of Safari, with the URL (fragment included) handed to the app. Public,
// unauthenticated, and identical on every instance by design.
func serveAASA(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	fmt.Fprintf(w, `{"applinks":{"details":[{"appIDs":[%q,%q],"components":[{"/":"/join/*"}]}]}}`, appleAppID, appleMacAppID)
}

// frontendVersion is a short hash of the embedded frontend (web/), computed once at
// startup. It changes whenever any UI file changes, so a redeploy that ships new
// frontend code yields a new version — clients notice and reload (see getVersion +
// the visibility check in chat.js). A server-only change leaves it unchanged.
func frontendVersion() string {
	h := sha256.New()
	_ = fs.WalkDir(webFS, "web", func(p string, d fs.DirEntry, err error) error {
		if err != nil || d.IsDir() {
			return nil
		}
		b, e := webFS.ReadFile(p)
		if e != nil {
			return nil
		}
		h.Write([]byte(p))
		h.Write(b)
		return nil
	})
	return fmt.Sprintf("%x", h.Sum(nil))[:12]
}

// getVersion returns the current frontend build hash (clients poll it to
// auto-reload) plus the binary build id. `version` drives the frontend reload;
// `build` is the compiled-in id `lchat deploy --version` health-checks against, so
// a deploy can confirm the intended binary is actually the one now serving.
func (s *Server) getVersion(w http.ResponseWriter, r *http.Request) {
	writeJSON(w, http.StatusOK, map[string]any{"version": s.version, "build": buildVersion})
}

// ChangelogEntry is one embedded release note (see the changelogFS comment).
// The text is operator-authored notes about the app itself — never user
// content — so, like roster labels, it lives in clear.
type ChangelogEntry struct {
	ID   string `json:"id"`   // filename without .md, e.g. 2026-07-01-helpers
	Text string `json:"text"` // the note, posted verbatim by the announcer
}

// loadChangelog reads the embedded entries once at startup, in filename order
// (date-prefixed names, so oldest first).
func loadChangelog() []ChangelogEntry {
	out := []ChangelogEntry{}
	files, _ := changelogFS.ReadDir("changelog")
	for _, f := range files { // ReadDir returns names sorted
		b, err := changelogFS.ReadFile("changelog/" + f.Name())
		if err != nil {
			continue
		}
		text := strings.TrimSpace(string(b))
		if text == "" {
			continue
		}
		out = append(out, ChangelogEntry{ID: strings.TrimSuffix(f.Name(), ".md"), Text: text})
	}
	return out
}

// getChangelog returns the embedded release notes. Token-gated like every data
// endpoint; the announcer bot reads it with its own device token.
func (s *Server) getChangelog(w http.ResponseWriter, r *http.Request) {
	if !s.tokenOK(r.URL.Query().Get("token")) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"entries": s.changelog})
}

// getAppGuide serves the embedded mini-app authoring guide as markdown. See the
// appGuideFS comment for why this endpoint is deliberately public.
func (s *Server) getAppGuide(w http.ResponseWriter, r *http.Request) {
	b, err := appGuideFS.ReadFile("docs/building-apps.md")
	if err != nil {
		httpError(w, http.StatusInternalServerError, "guide unavailable")
		return
	}
	w.Header().Set("Content-Type", "text/markdown; charset=utf-8")
	w.Write(b)
}

// getMemberAppGuide serves the sandboxed-tier authoring guide — what the
// assistant bot's create_app tool builds against (it fetches this exact
// endpoint, so bot and instance can never disagree on the rules), and what a
// member points an outside LLM at. Public like /api/app-guide.
func (s *Server) getMemberAppGuide(w http.ResponseWriter, r *http.Request) {
	// Apps off — or just member-built apps off — reads as "no guide": the
	// sidecar already treats a failed fetch as app building disabled, so a 404
	// switches its builder off with no new protocol between them.
	if !s.db.appsEnabled() || !s.db.memberAppsEnabled() {
		http.NotFound(w, r)
		return
	}
	b, err := appGuideFS.ReadFile("docs/building-member-apps.md")
	if err != nil {
		httpError(w, http.StatusInternalServerError, "guide unavailable")
		return
	}
	w.Header().Set("Content-Type", "text/markdown; charset=utf-8")
	w.Write(b)
}

// getAppChecker serves the embedded static app checker, so an author following
// the guide can run it without a repo checkout (curl -O, then node). Un-gated
// for the same reason as the guide: static tooling, not instance data.
func (s *Server) getAppChecker(w http.ResponseWriter, r *http.Request) {
	b, err := appGuideFS.ReadFile("tools/check-app.mjs")
	if err != nil {
		httpError(w, http.StatusInternalServerError, "checker unavailable")
		return
	}
	w.Header().Set("Content-Type", "text/javascript; charset=utf-8")
	w.Write(b)
}

// ---- chat API -----------------------------------------------------------

func (s *Server) getMessages(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	q := r.URL.Query()
	// Messages are per-thread; you must be a member of the thread you ask for.
	threadID := q.Get("thread")
	userID, _ := s.db.deviceTokenUser(token)
	if threadID == "" || !s.db.threadMember(threadID, userID) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	limit := 100
	if n, err := strconv.Atoi(q.Get("limit")); err == nil && n > 0 {
		limit = n
	}
	if limit > 200 {
		limit = 200
	}
	// `before` paginates older history (id < before); otherwise `after` returns
	// the page after a cursor, or the most recent `limit` when after is 0.
	var msgs []Message
	var err error
	if b := q.Get("before"); b != "" {
		before, _ := strconv.ParseInt(b, 10, 64)
		msgs, err = s.db.messagesBefore(threadID, before, limit)
	} else {
		after, _ := strconv.ParseInt(q.Get("after"), 10, 64)
		msgs, err = s.db.messagesAfter(threadID, after, limit)
	}
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"messages": msgs})
}

// postMessage is a non-WebSocket doorway to the exact same path as the "msg"
// frame in handleWS: a caller that holds a valid invite token POSTs an already
// AES-GCM-encrypted ciphertext blob, and we store + broadcast + push it. It lets
// bots, cron jobs and webhooks post without holding a WebSocket open.
//
// The end-to-end property is preserved precisely because the caller encrypts:
// the group key never reaches the server, and (as everywhere else) we store only
// the opaque blob and the author's hashed token — never plaintext. The companion
// `lchat-post` helper turns plaintext into the blob in the *caller's* trust
// domain.
func (s *Server) postMessage(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	// Cap the body before decoding so a valid-token holder can't force a huge
	// allocation — the length check below would fire too late on its own. Mirrors
	// uploadBlob's MaxBytesReader and handleWS's SetReadLimit.
	r.Body = http.MaxBytesReader(w, r.Body, maxBlobBytes+1024)
	var body struct {
		ThreadID string `json:"thread_id"`
		Blob     string `json:"blob"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// Same guards as the WebSocket "msg" case: non-empty, within the blob cap.
	if body.Blob == "" || len(body.Blob) > maxBlobBytes {
		httpError(w, http.StatusBadRequest, "missing or oversized blob")
		return
	}
	// Thread-scoped like every other write: the poster must be a member of the
	// thread (a script posts only where its user belongs). Same gate as the
	// WebSocket "msg" case.
	userID, _ := s.db.deviceTokenUser(token)
	if body.ThreadID == "" || !s.db.threadMember(body.ThreadID, userID) {
		httpError(w, http.StatusForbidden, "not a member of that thread")
		return
	}
	// Same closed-DM gate as the WebSocket "msg" case (issue #578).
	if closed, _ := s.db.dmClosed(body.ThreadID); closed {
		httpError(w, http.StatusForbidden, "conversation closed")
		return
	}
	// Same content-blind message brake as the WebSocket case (issue #578).
	if s.db.userRole(userID) != "admin" && !s.brake().messages.allow(userID) {
		httpError(w, http.StatusTooManyRequests, "sending too fast — give it a moment")
		return
	}
	m, err := s.db.insertMessage(body.ThreadID, body.Blob, userID)
	if err != nil {
		log.Println("insert message:", err)
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	out, _ := json.Marshal(wsOut{Type: "msg", ThreadID: body.ThreadID, ID: m.ID, CreatedAt: m.CreatedAt, Blob: m.Blob})
	s.broadcastToThread(body.ThreadID, out)
	// Notify the thread's other members (not the poster), best-effort, async.
	go s.pushNewMessage(m.Blob, body.ThreadID, token, m.ID, m.CreatedAt)
	writeJSON(w, http.StatusOK, m)
}

// brake returns the rate-limit set, creating it on first use — test servers
// build Server directly and must brake identically to production.
func (s *Server) brake() *modBrakes {
	if s.brakes == nil {
		s.brakes = newModBrakes()
	}
	return s.brakes
}

// tokenOK reports whether a token is a valid participant credential: either a
// current non-revoked invite (legacy) or a device token (invite redesign).
func (s *Server) tokenOK(token string) bool {
	if token == "" {
		return false
	}
	return s.db.deviceTokenValid(token)
}

// ---- threads & roster (see docs/threads-and-dms.md) ---------------------

// setPubkey registers the caller's ECDH public key in the roster (on first join,
// or after a key rotation). Members wrap thread keys to this.
func (s *Server) setPubkey(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		PublicKey string `json:"public_key"`
		// Key transparency (#573): HMAC of PublicKey under the invite secret T,
		// so a T-holder can verify the roster key. Opaque to us; stored beside
		// the key and served in the roster. Absent for pre-KT / add-device.
		BindMac string `json:"bind_mac"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	if len(body.BindMac) > 200 {
		httpError(w, http.StatusBadRequest, "bad bind mac")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if body.PublicKey == "" || len(body.PublicKey) > 500 {
		httpError(w, http.StatusBadRequest, "bad public key")
		return
	}
	// A user's public key is set once, on first join. Refuse to overwrite it with a
	// DIFFERENT key — that would orphan every thread wrapped to the old key (e.g. an
	// admin "device link" that made a new device generate its own keypair). Adding a
	// device ships the SAME keypair, so re-registering the identical key is fine.
	// A banned key can't re-register (issue #578) — this one gate covers every
	// invite path, because a member only becomes real once their key does.
	if s.db.keyBanned(body.PublicKey) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	firstKey := s.db.userPublicKey(uid) == ""
	if cur := s.db.userPublicKey(uid); cur != "" && cur != body.PublicKey {
		httpError(w, http.StatusConflict, "public key already registered")
		return
	}
	if err := s.db.setUserPublicKey(uid, body.PublicKey, body.BindMac); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// A fresh joiner is only NOW a keyed member — tell open tabs so the inviter's
	// pending-invite card swaps to the live DM (pendingInvitee needs a public key
	// to clear). Firing at claim time raced this POST and left the card stuck.
	if firstKey {
		out, _ := json.Marshal(map[string]any{"type": "joined", "user_id": uid})
		s.hub.broadcast <- outbound{data: out}
		// A cohort joiner is only NOW wrappable-to: prod each of their levels'
		// key holders (targeted, keyless). The holder backfill in loadTiers
		// self-heals later regardless; this makes the common case immediate.
		for _, tid := range s.db.userTiersNeedingKeys(uid) {
			s.prodTierHolders(tid, uid)
		}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// getRoster returns the caller's connections — themselves plus everyone they
// already share a thread with (a DM or a group). It is deliberately NOT the whole
// instance: you reach new people by inviting them, not by browsing a directory of
// everyone on the server. (A legacy token with no user gets an empty roster.)
func (s *Server) getRoster(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"roster": []RosterEntry{}})
		return
	}
	// Admin-vetted bots (agents in the Helpers catalog) see the full joined
	// roster, not just their connections: Eleven can't welcome a member it
	// can't see. This widens only what a *vetted bot* sees — people still get
	// connections-only, and an unvetted agent is treated like anyone else.
	var entries []RosterEntry
	var err error
	if s.db.isVettedAgent(uid) {
		entries, err = s.db.roster()
	} else {
		entries, err = s.db.connections(uid)
	}
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	s.stampPresence(entries)
	writeJSON(w, http.StatusOK, map[string]any{"roster": entries})
}

// getMe reports facts about the caller's own account — how many devices they
// have signed in (so the client can warn before signing out the last one, which
// loses their keys, and the chats encrypted to them, for good), and for admins
// whether they are the SOLE admin (so the home server's client can refuse to
// drop the last recovery copy of the only admin key without a teardown).
//
// The home page runs on a different origin, so this one endpoint answers CORS
// for exactly that origin — the response reveals nothing without a valid device
// token, and only the caller's own facts with one.
func (s *Server) getMe(w http.ResponseWriter, r *http.Request) {
	if o := r.Header.Get("Origin"); o != "" && o == s.homeOrigin {
		w.Header().Set("Access-Control-Allow-Origin", o)
		w.Header().Set("Vary", "Origin")
	}
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"device_count": 0})
		return
	}
	pinned, _ := s.db.userPresenceInfo(uid)
	me := map[string]any{
		"user_id":      uid,
		"device_count": s.db.deviceCount(uid),
		"role":         s.db.userRole(uid),
		// The caller's pinned Away flag (not the effective state) — what the
		// profile sheet's toggle reflects.
		"away": pinned == presenceAway,
		// setup_complete gates the first-run setup conversation. It's instance
		// state (not a secret), but only an admin's client acts on it.
		"setup_complete": s.db.setupComplete(),
	}
	// Only admins learn the admin headcount fact — members have no use for it.
	if me["role"] == "admin" {
		me["sole_admin"] = s.db.adminCount() == 1
	}
	// DM privacy (issue #578): what the caller's own settings toggle reflects.
	me["dm_privacy"] = s.db.userDMPrivacy(uid)
	writeJSON(w, http.StatusOK, me)
}

// signout revokes the caller's own device token (sign out on this device) and drops
// its push subscriptions. Other devices keep working; the key survives on them.
func (s *Server) signout(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// Token-gate like every data endpoint; an unknown token has nothing to revoke, so
	// treat it as already signed out (idempotent) rather than acting on it.
	if !s.tokenOK(body.Token) {
		writeJSON(w, http.StatusOK, map[string]any{"ok": true})
		return
	}
	_ = s.db.deleteDeviceToken(body.Token)
	_ = s.db.deleteSubscriptionsForToken(body.Token)
	_ = s.db.deleteAPNsTokensForToken(body.Token)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// getThreads returns the caller's threads, each with their wrapped key + members.
func (s *Server) getThreads(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"threads": []Thread{}})
		return
	}
	ts, err := s.db.threadsForUser(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"threads": ts})
}

// postThread creates a DM, group, or self thread. The browser generates the
// thread key and wraps it to each member's roster public key; the server only
// stores the (server-blind) blobs. The caller must include themselves. DMs are
// deduped to one per pair.
func (s *Server) postThread(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token      string            `json:"token"`
		Kind       string            `json:"kind"`
		NameBlob   string            `json:"name_blob"`
		Members    []ThreadMemberKey `json:"members"`
		Visibility string            `json:"visibility"`
		OpenKey    string            `json:"open_key"`
		OpenTier   string            `json:"open_tier"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if body.Kind != "self" && body.Kind != "dm" && body.Kind != "group" {
		httpError(w, http.StatusBadRequest, "bad kind")
		return
	}
	if (body.Kind == "self" && len(body.Members) != 1) ||
		(body.Kind == "dm" && len(body.Members) != 2) ||
		(body.Kind == "group" && len(body.Members) < 1) {
		httpError(w, http.StatusBadRequest, "bad member count")
		return
	}
	// Open community groups: group-only, and the client must supply open_key —
	// the thread key encrypted under the instance key (opaque to the server) —
	// so any member can later discover, decrypt, and self-join.
	if body.Visibility != "" && body.Visibility != "invite" && body.Visibility != "open" {
		httpError(w, http.StatusBadRequest, "bad visibility")
		return
	}
	open := body.Visibility == "open"
	if open && body.Kind != "group" {
		httpError(w, http.StatusBadRequest, "only groups can be open")
		return
	}
	if (open && (body.OpenKey == "" || len(body.OpenKey) > 4096)) || (!open && body.OpenKey != "") {
		httpError(w, http.StatusBadRequest, "bad open key")
		return
	}
	// A level gate rides only on open groups, and only a member of that level
	// can set it — they wrapped open_key under the level's key, which only
	// members hold (the server can verify membership, not the wrap itself).
	if body.OpenTier != "" && (!open || !s.db.tierExists(body.OpenTier) || !s.db.tierMember(body.OpenTier, uid)) {
		httpError(w, http.StatusBadRequest, "bad access level")
		return
	}
	inSet := false
	for _, m := range body.Members {
		// An open group's members may omit their per-member wrap — the key
		// reaches everyone via open_key instead.
		if (m.Wrapped == "" && !open) || len(m.Wrapped) > 4096 || !s.db.userExists(m.UserID) {
			httpError(w, http.StatusBadRequest, "bad member")
			return
		}
		if m.UserID == uid {
			inSet = true
		}
	}
	if !inSet {
		httpError(w, http.StatusForbidden, "must include yourself")
		return
	}
	// DM dedupe: one thread per pair.
	if body.Kind == "dm" {
		other := body.Members[0].UserID
		if other == uid {
			other = body.Members[1].UserID
		}
		if existing, found, _ := s.db.dmThreadFor(uid, other); found {
			writeJSON(w, http.StatusOK, map[string]any{"thread_id": existing, "existing": true})
			return
		}
		// DM privacy (issue #578): a NEW DM respects the other person's door.
		// An existing conversation (above) is untouched — the setting governs
		// opening contact, not history.
		if !s.dmAllowed(uid, other) {
			httpError(w, http.StatusForbidden, "dms closed")
			return
		}
		// The mass-DM brake (issue #578): fresh members get the tighter
		// first-day bucket — the classic spam-join opens DMs immediately.
		if s.db.userRole(uid) != "admin" && !s.db.isAgent(uid) && !s.allowDM(uid, s.db.userCreatedAt(uid)) {
			httpError(w, http.StatusTooManyRequests, "opening chats too fast — give it a moment")
			return
		}
	}
	id, err := s.db.createThreadVis(body.Kind, body.NameBlob, body.Members, body.Visibility, body.OpenKey, body.OpenTier)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if body.Kind == "dm" {
		other := body.Members[0].UserID
		if other == uid {
			other = body.Members[1].UserID
		}
		// recordDMPair fails on the dm_pairs PK if a concurrent request already
		// created the DM. In that case drop the duplicate thread we just made and
		// return the winner, so a fast double-tap can't spawn two DM threads.
		if err := s.db.recordDMPair(uid, other, id); err != nil {
			if existing, found, _ := s.db.dmThreadFor(uid, other); found {
				_ = s.db.deleteThread(id)
				writeJSON(w, http.StatusOK, map[string]any{"thread_id": existing, "existing": true})
				return
			}
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	writeJSON(w, http.StatusOK, map[string]any{"thread_id": id})
}

// getOpenThreads lists the community directory: every open group, joined or
// not, each carrying its instance-key-wrapped open_key so any member's client
// can decrypt names/photos and self-join. Members only — never public: someone
// outside the space sees nothing.
func (s *Server) getOpenThreads(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"threads": []OpenThread{}})
		return
	}
	ts, err := s.db.openThreads(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"threads": ts})
}

// postThreadJoin self-serve-joins the caller to an open group. No key material
// changes hands: the joiner already holds the instance key, and the group's
// open_key rides their next thread-list fetch.
func (s *Server) postThreadJoin(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if err := s.db.joinOpenThread(r.PathValue("id"), uid); err != nil {
		if errors.Is(err, errNotOpen) {
			httpError(w, http.StatusForbidden, "not an open group")
			return
		}
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadVisibility opens or closes a group for discovery. Any member may
// flip it (groups are flat, like rename). Opening requires open_key — the
// thread key encrypted under the instance key by the caller's browser; the
// server can open neither. An existing open_key is never overwritten (see
// setThreadVisibility), and closing keeps it so self-serve joiners keep their
// key source — 'invite' only stops discovery and new joins.
func (s *Server) postThreadVisibility(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token      string `json:"token"`
		Visibility string `json:"visibility"`
		OpenKey    string `json:"open_key"`
		OpenTier   string `json:"open_tier"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	if s.db.threadKind(threadID) != "group" {
		httpError(w, http.StatusBadRequest, "only groups can be open")
		return
	}
	open := body.Visibility == "open"
	if body.Visibility != "invite" && !open {
		httpError(w, http.StatusBadRequest, "bad visibility")
		return
	}
	hasKey, curTier := s.db.threadOpenInfo(threadID)
	// First open requires the key blob; a REOPEN must not (the stored
	// open_key survives closing and is never overwritten) — otherwise only
	// wrap-key holders could reopen, while any member could close.
	if (open && !hasKey && (body.OpenKey == "" || len(body.OpenKey) > 4096)) ||
		len(body.OpenKey) > 4096 || (!open && body.OpenKey != "") {
		httpError(w, http.StatusBadRequest, "bad open key")
		return
	}
	// A NEW gate needs its setter to be in the level (they wrapped open_key
	// under the level's key, which only members hold). Re-naming the stored
	// gate on reopen moves no key material, so it needs no such check.
	if body.OpenTier != "" && body.OpenTier != curTier &&
		(!open || !s.db.tierExists(body.OpenTier) || !s.db.tierMember(body.OpenTier, uid)) {
		httpError(w, http.StatusBadRequest, "bad access level")
		return
	}
	// The gate is fixed once an open_key exists (changing it would need the
	// rekey the never-overwrite rule forbids) — refuse loudly rather than
	// letting a caller believe the gate moved.
	if open && hasKey && body.OpenTier != curTier {
		httpError(w, http.StatusBadRequest, "access level is fixed once a group has opened")
		return
	}
	if err := s.db.setThreadVisibility(threadID, body.Visibility, body.OpenKey, body.OpenTier); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadDefault flags an open group as joined-by-default for new members
// (Slack's #general). Space policy rather than group housekeeping, so unlike
// rename/visibility it's admin-role-gated, not any-member. Only open groups
// can default (a default group must be self-joinable); unflagging is always
// allowed. Existing members are never force-joined.
func (s *Server) postThreadDefault(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token   string `json:"token"`
		Default bool   `json:"default"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || s.db.userRole(uid) != "admin" {
		httpError(w, http.StatusForbidden, "admins only")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	if body.Default && !s.db.threadIsOpen(threadID) {
		httpError(w, http.StatusBadRequest, "only open groups can be default")
		return
	}
	// The default sweep deliberately skips level-gated groups (a newcomer
	// holds no level yet) — refuse the flag rather than save-and-ignore it.
	if _, gate := s.db.threadOpenInfo(threadID); body.Default && gate != "" {
		httpError(w, http.StatusBadRequest, "limited groups can't be default")
		return
	}
	if err := s.db.setThreadDefault(threadID, body.Default); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadMember adds an existing instance member to a thread the caller is in.
// The caller's browser wraps the thread key to the new member's public key.
func (s *Server) postThreadMember(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token   string `json:"token"`
		UserID  string `json:"user_id"`
		Wrapped string `json:"wrapped"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	// Only groups grow. Adding to a DM/self thread would break the one-thread-per-
	// pair invariant (dm_pairs) and silently turn a 2-person DM into a 3-way thread.
	if s.db.threadKind(threadID) != "group" {
		httpError(w, http.StatusBadRequest, "can only add people to a group")
		return
	}
	if body.UserID == "" || !s.db.userExists(body.UserID) || body.Wrapped == "" || len(body.Wrapped) > 4096 {
		httpError(w, http.StatusBadRequest, "bad member")
		return
	}
	// A block cuts indirect contact too (issue #578): neither side can pull
	// the other into a group. Same generic refusal as elsewhere — the add just
	// doesn't work, with no hint of which mechanism said no.
	if s.db.blockedEither(uid, body.UserID) {
		httpError(w, http.StatusForbidden, "can't add this member")
		return
	}
	// Adding an existing member is a no-op, checked here on purpose: a
	// self-serve joiner of an open group has membership but no thread_keys
	// row, and that empty slot must not be fillable with another member's
	// arbitrary blob (addThreadMember's DO NOTHING only protects rows that
	// already exist). The one sanctioned fill-an-existing-member's-slot path
	// is invite claiming, which writes the joiner's OWN wrap (claimKeyInvite).
	if s.db.threadMember(threadID, body.UserID) {
		writeJSON(w, http.StatusOK, map[string]any{"ok": true})
		return
	}
	if err := s.db.addThreadMember(threadID, body.UserID, body.Wrapped); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadName renames a thread (the group name is client-encrypted, so the
// server only stores the new blob). Any member may rename.
func (s *Server) postThreadName(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token    string `json:"token"`
		NameBlob string `json:"name_blob"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || len(body.NameBlob) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	// The space thread has no name to set (no sidebar row, no chat view) —
	// with implicit membership every member would pass the gate above, so
	// fence the write off rather than leave a pointless scribble surface.
	if s.db.threadKind(threadID) == "space" {
		httpError(w, http.StatusBadRequest, "the space thread has no name")
		return
	}
	if err := s.db.setThreadName(threadID, body.NameBlob); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// getInstanceKey returns the caller's wrapped instance key (if granted) plus the
// list of users who already hold it, so a holder only re-wraps to those missing.
func (s *Server) getInstanceKey(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"wrapped": "", "have": []string{}})
		return
	}
	wrapped, _, err := s.db.instanceKeyFor(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	have, err := s.db.instanceKeyHolders()
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	out := map[string]any{"wrapped": wrapped, "have": have}
	// A keyless member waiting on holders gets liveness alongside (#785):
	// whether any holder is connected right now, and the newest read
	// watermark among them — enough for the client to say "the members who
	// hold this space's key haven't been online since May" instead of an
	// eternal "still setting up". Metadata the server already holds (it owns
	// the sockets and the read marks); no key material rides on it.
	if wrapped == "" && len(have) > 0 {
		online := false
		for _, h := range have {
			if s.presence.connected(h) {
				online = true
				break
			}
		}
		lastActive, err := s.db.lastReadActivity(have)
		if err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		out["holders_online"] = online
		out["holders_last_active"] = lastActive
	}
	writeJSON(w, http.StatusOK, out)
}

// resetInstanceKeyHandler is the break-glass for an orphaned instance key
// (#785): admin-gated, destructive by design (the old key's sealed blobs are
// gone for good — the web admin console spells that out before calling). The
// next member to load the app bootstraps a fresh key.
func (s *Server) resetInstanceKeyHandler(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	if err := s.db.resetInstanceKey(); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postInstanceKey stores the (server-blind) instance key wrapped to one or more
// members — used to bootstrap it and to grant it to members who lack it.
func (s *Server) postInstanceKey(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string            `json:"token"`
		Grants []ThreadMemberKey `json:"grants"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	if _, ok := s.db.deviceTokenUser(body.Token); !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	granted := map[string]bool{}
	for _, g := range body.Grants {
		if g.UserID == "" || g.Wrapped == "" || len(g.Wrapped) > 4096 || !s.db.userExists(g.UserID) {
			continue
		}
		if err := s.db.grantInstanceKey(g.UserID, g.Wrapped); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		granted[g.UserID] = true
	}
	// Nudge the just-granted users' open tabs to fetch + unwrap right away, so a
	// member stops showing "Photo syncing…" the instant a holder wraps the key to
	// them — without waiting for a reload. Keyless signal, routed only to them.
	if len(granted) > 0 {
		out, _ := json.Marshal(map[string]any{"type": "instance_key_granted"})
		s.hub.broadcast <- outbound{members: granted, data: out}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// nudgeInstanceKey is called by a member who holds no copy of the instance key. It
// relays a keyless "someone needs it" hint to every connected client; holders
// respond by (re-)wrapping the key to whoever's missing it (see the WS handler +
// grantInstanceKeyTo in the client). Carries no key material — just a prod, so a
// new member doesn't have to wait for a holder to next reboot.
func (s *Server) nudgeInstanceKey(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	// Carry who's asking and their public key: a holder's own roster view
	// (connections) may not include the nudger at all — a fresh joiner shares
	// no thread with most members — so holders wrap to this key directly.
	msg := map[string]any{"type": "instance_key_nudge"}
	if uid, ok := s.db.deviceTokenUser(token); ok {
		if pub := s.db.userPublicKey(uid); pub != "" {
			msg["user_id"] = uid
			msg["public_key"] = pub
		}
	}
	out, _ := json.Marshal(msg)
	s.hub.broadcast <- outbound{data: out} // members:nil → everyone
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// adminTiers lists the access levels for the admin console's cohort picker
// (bearer-token surface — the console holds no member token). Same rows the
// member endpoint serves, unpersonalised.
func (s *Server) adminTiers(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	ts, err := s.db.listTiers("", true)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"tiers": ts})
}

// ---- tiers ----------------------------------------------------------------
// Admin-curated member sets that carry key material (docs/community-and-tiers.md).
// The key machinery is the instance key's, per tier: clients mint and wrap the
// key, the server stores blobs it can't open, grants never overwrite, and WS
// prods are keyless hints. Management (create/assign/remove/delete) is
// admin-ROLE-gated — tiers are space policy, like default groups.

// tierAdmin resolves the caller and requires the admin role. Returns ("",
// false) after writing the error when the gate fails.
func (s *Server) tierAdmin(w http.ResponseWriter, token string) (string, bool) {
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return "", false
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok || s.db.userRole(uid) != "admin" {
		httpError(w, http.StatusForbidden, "admins only")
		return "", false
	}
	return uid, true
}

// getTiers lists every tier for any member (names are plaintext space policy,
// like the roster), personalised with the caller's membership + key state.
func (s *Server) getTiers(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, map[string]any{"tiers": []Tier{}})
		return
	}
	ts, err := s.db.listTiers(uid, s.db.userRole(uid) == "admin")
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"tiers": ts})
}

func (s *Server) postTier(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
		Name  string `json:"name"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if _, ok := s.tierAdmin(w, body.Token); !ok {
		return
	}
	name := strings.TrimSpace(body.Name)
	if name == "" || utf8.RuneCountInString(name) > 60 {
		httpError(w, http.StatusBadRequest, "bad name")
		return
	}
	id, err := s.db.createTier(name)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"id": id})
}

func (s *Server) deleteTierHandler(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if _, ok := s.tierAdmin(w, body.Token); !ok {
		return
	}
	id := r.PathValue("id")
	// A level that still gates groups can't be deleted: those groups' keys
	// are wrapped under it forever, and for self-serve joiners that wrap is
	// their only key source (see deleteTier's comment).
	if n := s.db.tierGatesThreads(id); n > 0 {
		httpError(w, http.StatusConflict, "this level still limits groups")
		return
	}
	if err := s.db.deleteTier(id); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postTierMember assigns a member to a tier ('admin' source). The prod fans
// out two keyless hints: holders learn someone needs the key wrapped to them
// (so an online holder acts immediately, no reload), and the assignee's own
// tabs learn their tiers changed.
func (s *Server) postTierMember(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		UserID string `json:"user_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if _, ok := s.tierAdmin(w, body.Token); !ok {
		return
	}
	tierID := r.PathValue("id")
	if !s.db.tierExists(tierID) || !s.db.userExists(body.UserID) {
		httpError(w, http.StatusBadRequest, "bad tier or member")
		return
	}
	if err := s.db.assignTier(tierID, body.UserID, "admin"); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	s.prodTierHolders(tierID, body.UserID)
	s.prodTiersChanged(body.UserID)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

func (s *Server) postTierRemove(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		UserID string `json:"user_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	uid, ok := s.tierAdmin(w, body.Token)
	if !ok {
		return
	}
	if err := s.db.unassignTier(r.PathValue("id"), body.UserID); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Taking an access level away is a moderation-grade action (the "demote"
	// rung on the ladder, issue #578) — record it.
	s.db.addAudit(uid, "level.removed", body.UserID, "", "", r.PathValue("id"))
	s.prodTiersChanged(body.UserID)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postTierKeys stores wrapped tier-key copies. Two callers are legitimate:
// the MINT moment (no copies exist yet — admin-only, their client just
// generated the key and wrapped it to the initial members), and a HOLDER
// wrapping to members who joined since. Grants only land on tier members,
// and never overwrite (grantTierKey).
func (s *Server) postTierKeys(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string            `json:"token"`
		Grants []ThreadMemberKey `json:"grants"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	tierID := r.PathValue("id")
	if !s.db.tierExists(tierID) {
		httpError(w, http.StatusBadRequest, "no such tier")
		return
	}
	valid := []ThreadMemberKey{}
	granted := map[string]bool{}
	for _, g := range body.Grants {
		if g.UserID == "" || g.Wrapped == "" || len(g.Wrapped) > 4096 || !s.db.tierMember(tierID, g.UserID) {
			continue
		}
		valid = append(valid, g)
		granted[g.UserID] = true
	}
	if !s.db.tierKeyMinted(tierID) {
		// The mint moment — admin-only, one-way, transactional: concurrent
		// minters serialize on key_minted, exactly one key ever enters a
		// level. The loser gets 409 and must reload (never install its key).
		if s.db.userRole(uid) != "admin" {
			httpError(w, http.StatusForbidden, "admins only")
			return
		}
		if err := s.db.mintTierKeys(tierID, valid); err != nil {
			if errors.Is(err, errAlreadyMinted) {
				httpError(w, http.StatusConflict, "already minted")
				return
			}
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	} else if s.db.tierKeyCount(tierID) == 0 {
		// Minted once, but every holder is gone — the key is unrecoverable.
		// Refuse loudly instead of silently minting a second key that would
		// seal every group gated under the first: the honest path is to
		// delete this level and create a fresh one.
		httpError(w, http.StatusGone, "this level's key is lost — delete the level and create a new one")
		return
	} else {
		if !s.db.tierHolder(tierID, uid) {
			httpError(w, http.StatusForbidden, "not a key holder")
			return
		}
		for _, g := range valid {
			if err := s.db.grantTierKey(tierID, g.UserID, g.Wrapped); err != nil {
				httpError(w, http.StatusInternalServerError, "db error")
				return
			}
		}
	}
	if len(granted) > 0 {
		out, _ := json.Marshal(map[string]any{"type": "tier_key_granted", "tier_id": tierID})
		s.hub.broadcast <- outbound{members: granted, data: out}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// nudgeTierKey: a tier member with no key copy asks for one. Unlike the
// instance-key nudge (everyone), this prods exactly the members who can help —
// current holders. Keyless, like every prod.
func (s *Server) nudgeTierKey(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	tierID := r.PathValue("id")
	if !s.db.tierMember(tierID, uid) {
		httpError(w, http.StatusForbidden, "not in this tier")
		return
	}
	s.prodTierHolders(tierID, uid)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postTierPolicy sets a level's visibility policy — admin-gated (it's space
// policy, like management). 'shown' | 'hidden' | 'user'.
func (s *Server) postTierPolicy(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		Policy string `json:"policy"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if _, ok := s.tierAdmin(w, body.Token); !ok {
		return
	}
	if body.Policy != "shown" && body.Policy != "hidden" && body.Policy != "user" {
		httpError(w, http.StatusBadRequest, "bad policy")
		return
	}
	if !s.db.tierExists(r.PathValue("id")) {
		httpError(w, http.StatusBadRequest, "no such level")
		return
	}
	if err := s.db.setTierVisibility(r.PathValue("id"), body.Policy); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postTierShow is a member's own show/hide choice for a level they're in —
// honoured only while the level's policy is 'user' (else the admin policy
// decides). Members choose whether THEIR membership shows to non-members.
func (s *Server) postTierShow(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
		Show  bool   `json:"show"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if !s.db.tierMember(r.PathValue("id"), uid) {
		httpError(w, http.StatusForbidden, "not in this level")
		return
	}
	if err := s.db.setUserTierVisible(r.PathValue("id"), uid, body.Show); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// prodTierHolders tells current key holders that userID needs the tier key
// wrapped to them — carrying the target's pubkey, since a holder's roster
// view may not include a fresh joiner (the instance-key nudge's reasoning).
func (s *Server) prodTierHolders(tierID, userID string) {
	holders, err := s.db.tierHolderIDs(tierID)
	if err != nil || len(holders) == 0 {
		return
	}
	pub := s.db.userPublicKey(userID)
	if pub == "" {
		return
	}
	set := map[string]bool{}
	for _, h := range holders {
		if h != userID {
			set[h] = true
		}
	}
	if len(set) == 0 {
		return
	}
	out, _ := json.Marshal(map[string]any{
		"type": "tier_key_nudge", "tier_id": tierID, "user_id": userID, "public_key": pub,
	})
	s.hub.broadcast <- outbound{members: set, data: out}
}

// prodTiersChanged tells one member's own tabs their tier set changed.
func (s *Server) prodTiersChanged(userID string) {
	out, _ := json.Marshal(map[string]any{"type": "tiers_changed"})
	s.hub.broadcast <- outbound{members: map[string]bool{userID: true}, data: out}
}

// postLabel sets the caller's own display name, encrypted under the instance key
// (a server-blind blob). This is how a person publishes their name — the server
// never sees the plaintext. Broadcasts so every client refreshes the roster name.
func (s *Server) postLabel(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		LabelBlob string `json:"label_blob"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || body.LabelBlob == "" || len(body.LabelBlob) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if err := s.db.setUserLabelBlob(uid, body.LabelBlob); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	out, _ := json.Marshal(map[string]any{"type": "label", "user_id": uid, "label_blob": body.LabelBlob})
	s.hub.broadcast <- outbound{data: out}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postLabelBackfill seals another member's LEGACY plaintext label under the
// instance key (docs/no-plaintext.md): any member's client that holds the key
// may do this on roster load, so one visit from anyone scrubs names members
// left at rest before label_blob existed. The DB gate is strictly fill-once
// (people only, plaintext still present, no existing blob), so an HONEST
// client only re-encodes the name the server already stored. The server
// cannot verify the blob's content (it has no key), so a malicious MEMBER
// could seal a different name here — a deliberate, narrow trade: it needs a
// roster member holding the instance key, it works once per legacy row only,
// it touches nothing but a display name, and the victim re-setting their name
// overrides it. The alternative (leaving inactive members' real names in
// plaintext at rest, forever) loses to that.
func (s *Server) postLabelBackfill(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		UserID    string `json:"user_id"`
		LabelBlob string `json:"label_blob"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	if body.UserID == "" || body.LabelBlob == "" || len(body.LabelBlob) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	filled, err := s.db.backfillUserLabelBlob(body.UserID, body.LabelBlob)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if filled {
		out, _ := json.Marshal(map[string]any{"type": "label", "user_id": body.UserID, "label_blob": body.LabelBlob})
		s.hub.broadcast <- outbound{data: out}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "filled": filled})
}

// postAvatar sets the caller's profile photo (an encrypted blob id, or "" to clear).
func (s *Server) postAvatar(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		BlobID string `json:"blob_id"`
		// The photo's alt text, encrypted under the instance key by the client
		// (opaque here, like the label blob).
		AltBlob string `json:"alt_blob"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || len(body.BlobID) > 200 || len(body.AltBlob) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if err := s.db.setAvatar(uid, body.BlobID, body.AltBlob); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Tell every connected client to refresh this user's avatar (profile photos
	// are instance-wide). members:nil → broadcast to everyone.
	out, _ := json.Marshal(map[string]any{"type": "avatar", "user_id": uid, "blob_id": body.BlobID, "alt_blob": body.AltBlob})
	s.hub.broadcast <- outbound{data: out}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postDescription sets the caller's own "about me" text, encrypted under the
// instance key by their client ("" clears it). Opaque here, like the label blob.
func (s *Server) postDescription(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token           string `json:"token"`
		DescriptionBlob string `json:"description_blob"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || len(body.DescriptionBlob) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if err := s.db.setUserDescriptionBlob(uid, body.DescriptionBlob); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	out, _ := json.Marshal(map[string]any{"type": "description", "user_id": uid, "description_blob": body.DescriptionBlob})
	s.hub.broadcast <- outbound{data: out}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// The caller's per-viewer name overrides (issue #577): one blob holding every
// "I call them Dermo", sealed by the client to the caller's OWN public key.
// Viewer-private user content — it never rides the roster and never broadcasts
// (a nickname is nobody else's business, not even its subject's); only the
// owner's devices, which share the keypair, can open it. Opaque here, as ever.
func (s *Server) getNicknames(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	blob, version, err := s.db.userNicknamesBlob(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"nicknames_blob": blob, "version": version})
}

func (s *Server) postNicknames(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token         string `json:"token"`
		NicknamesBlob string `json:"nicknames_blob"`
		// The version the writer last read (compare-and-swap). A pointer so
		// absent is distinguishable from 0: a pre-versioning client omits it
		// and keeps its unconditional write.
		Version *int64 `json:"version"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	// One sealed entry is ~100 bytes of ciphertext; 64 KiB covers hundreds of
	// members with room to spare (the description's 4 KiB is one field, this
	// blob is a whole map).
	if !ok || len(body.NicknamesBlob) > 64*1024 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	base := int64(-1)
	if body.Version != nil && *body.Version >= 0 {
		base = *body.Version
	}
	version, wrote, err := s.db.setUserNicknamesBlob(uid, body.NicknamesBlob, base)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if !wrote {
		// Another device wrote since the caller's read — 409 with where the
		// row is now, so it can re-read, replay its queued ops, and retry.
		writeJSON(w, http.StatusConflict, map[string]any{"error": "version conflict", "version": version})
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "version": version})
}

// The caller's private moderation preferences (muted people, for now): one
// blob sealed by the client to the caller's OWN public key, exactly like the
// nicknames blob. Who you mute is nobody else's business — not the muted
// person's, not the server's; only the owner's devices can open it.
func (s *Server) getPrefs(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	blob, version, err := s.db.userPrefsBlob(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"prefs_blob": blob, "version": version})
}

func (s *Server) postPrefs(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		PrefsBlob string `json:"prefs_blob"`
		// The version the writer last read (compare-and-swap); absent skips
		// the check, like the nicknames blob.
		Version *int64 `json:"version"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	// A muted-people set is one sealed entry per person (~100 bytes each);
	// 64 KiB is the same generous ceiling the nicknames blob uses.
	if !ok || len(body.PrefsBlob) > 64*1024 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	base := int64(-1)
	if body.Version != nil && *body.Version >= 0 {
		base = *body.Version
	}
	version, wrote, err := s.db.setUserPrefsBlob(uid, body.PrefsBlob, base)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if !wrote {
		writeJSON(w, http.StatusConflict, map[string]any{"error": "version conflict", "version": version})
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "version": version})
}

// postGroupDescription sets the space's description (admin only — the space's
// self-portrait is a branding decision, like its name). Plaintext, like the
// admin name/email: it must be editable from the keyless admin console and
// readable on the join card before an invitee holds any key. "" clears it.
func (s *Server) postGroupDescription(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	if !s.requireUnsealed(w) {
		return
	}
	var body struct {
		Description string `json:"description"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	desc := strings.TrimSpace(body.Description)
	if len(desc) > 1000 { // ~500 chars even in multi-byte scripts
		httpError(w, http.StatusBadRequest, "too long")
		return
	}
	if err := s.db.setGroupDescription(desc); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "description": desc})
}

// postThreadAvatar sets a group's photo (an encrypted blob id). Any member may.
func (s *Server) postThreadAvatar(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		BlobID string `json:"blob_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || len(body.BlobID) > 200 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	// Same fence as postThreadName: the space thread renders nowhere, so a
	// photo on it is only a scribble surface implicit membership would open.
	if s.db.threadKind(threadID) == "space" {
		httpError(w, http.StatusBadRequest, "the space thread has no photo")
		return
	}
	if err := s.db.setThreadAvatar(threadID, body.BlobID); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Refresh the group photo for the thread's members (only they can see it).
	out, _ := json.Marshal(map[string]any{"type": "thread_avatar", "thread_id": threadID, "blob_id": body.BlobID})
	s.broadcastToThread(threadID, out)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadLeave removes the caller from a thread.
func (s *Server) postThreadLeave(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if err := s.db.removeThreadMember(r.PathValue("id"), uid); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadHidden closes (hidden=true) or reopens (hidden=false) a chat for the
// caller — a per-user marker that syncs across their devices. Any member may set
// it on their own view; it never affects anyone else.
func (s *Server) postThreadHidden(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		Hidden bool   `json:"hidden"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	if err := s.db.setThreadHidden(uid, threadID, body.Hidden); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadPinned pins (pinned=true) or unpins (pinned=false) a chat for the
// caller — a per-user marker that syncs across their devices and floats the
// thread to the top of their list. It never affects anyone else.
func (s *Server) postThreadPinned(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		Pinned bool   `json:"pinned"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	if err := s.db.setThreadPinned(uid, threadID, body.Pinned); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// dmAllowed says whether `from` may open a NEW DM with `to`. Admins and bots
// pass a closed door — the space's operator must stay reachable, and
// onboarding speaks through Eleven's welcome DM — and the setting's UI copy
// says so out loud rather than implying an absolute wall.
func (s *Server) dmAllowed(from, to string) bool {
	// Admins and bots pass both doors — the operator must stay reachable (a
	// reported member could otherwise dodge a formal warning by blocking the
	// admin), and onboarding speaks through Eleven's welcome DM.
	if s.db.userRole(from) == "admin" || s.db.isAgent(from) {
		return true
	}
	// A block cuts contact in both directions, whoever asks (issue #578) —
	// the blocker unblocks first if they change their mind.
	if s.db.blockedEither(from, to) {
		return false
	}
	return s.db.userDMPrivacy(to) != "nobody"
}

// postDMPrivacy sets the caller's own DM door: "" / "everyone" (anyone in the
// space may open a DM with them) or "nobody". Enforced at DM creation — see
// dmAllowed.
func (s *Server) postDMPrivacy(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		DMPrivacy string `json:"dm_privacy"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	v := body.DMPrivacy
	if v == "everyone" {
		v = "" // the default, stored lean
	}
	if v != "" && v != "nobody" {
		httpError(w, http.StatusBadRequest, "bad dm_privacy")
		return
	}
	if err := s.db.setUserDMPrivacy(uid, v); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "dm_privacy": v})
}

// getBlocks lists who the caller has blocked — their own list only.
func (s *Server) getBlocks(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	list, err := s.db.blocksOf(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"blocked": list})
}

// postBlock blocks a member (issue #578): records the no-new-contact rule and
// ends any existing DM with them (the closed-DM machinery, so message/edit/
// typing refusals and the closed banner all follow). The blocked party is
// never told — they see the same silence and generic refusals a closed DM
// door produces.
func (s *Server) postBlock(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		UserID string `json:"user_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if body.UserID == "" || body.UserID == uid || !s.db.userExists(body.UserID) {
		httpError(w, http.StatusBadRequest, "bad user_id")
		return
	}
	if err := s.db.setBlocked(uid, body.UserID, true); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Block implies the conversation ends now, not at the next refusal.
	if tid, found, _ := s.db.dmThreadFor(uid, body.UserID); found {
		if closed, _ := s.db.dmClosed(tid); !closed {
			_ = s.db.closeDM(tid, uid)
			members, _ := s.db.memberUserIDs(tid)
			set := map[string]bool{}
			for _, m := range members {
				_ = s.db.setThreadHidden(m, tid, true)
				set[m] = true
			}
			out, _ := json.Marshal(map[string]any{"type": "dm_closed", "thread_id": tid})
			s.hub.broadcast <- outbound{members: set, data: out}
		}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// deleteBlock unblocks. Deliberately narrow: the DM stays closed (reopen is
// its own step, through the other person's DM door) and any client-side mute
// stays put — unblocking restores the possibility of contact, nothing more.
func (s *Server) deleteBlock(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if err := s.db.setBlocked(uid, r.PathValue("id"), false); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postCloseDM ends a DM for both parties (issue #578): it drops off both
// lists and the server refuses new traffic into it until someone reopens it.
// Distinct from hiding (which quietly returns on activity) and from blocking
// (which is about the person): closing is about this conversation.
func (s *Server) postCloseDM(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	if s.db.threadKind(threadID) != "dm" {
		httpError(w, http.StatusBadRequest, "not a dm")
		return
	}
	if err := s.db.closeDM(threadID, uid); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Drop it from both lists (per-user hidden markers), and tell both sides'
	// live clients so open panes swap to the closed banner at once.
	members, _ := s.db.memberUserIDs(threadID)
	set := map[string]bool{}
	for _, m := range members {
		_ = s.db.setThreadHidden(m, threadID, true)
		set[m] = true
	}
	out, _ := json.Marshal(map[string]any{"type": "dm_closed", "thread_id": threadID})
	s.hub.broadcast <- outbound{members: set, data: out}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postReopenDM reopens a closed DM. Either side may — but through the other
// person's DM door: if they've since closed DMs, reopening follows their
// setting (the same dmAllowed gate as opening a fresh DM).
func (s *Server) postReopenDM(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	closed, _ := s.db.dmClosed(threadID)
	if !closed {
		writeJSON(w, http.StatusOK, map[string]any{"ok": true}) // already open
		return
	}
	other, _ := s.db.otherThreadMember(threadID, uid)
	if other != "" && !s.dmAllowed(uid, other) {
		httpError(w, http.StatusForbidden, "dms closed")
		return
	}
	if err := s.db.reopenDM(threadID); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// The reopener sees it again now; the other side stays hidden until the
	// first new message unhides it (insertMessage's clearThreadHidden).
	_ = s.db.setThreadHidden(uid, threadID, false)
	members, _ := s.db.memberUserIDs(threadID)
	set := map[string]bool{}
	for _, m := range members {
		set[m] = true
	}
	out, _ := json.Marshal(map[string]any{"type": "dm_reopened", "thread_id": threadID})
	s.hub.broadcast <- outbound{members: set, data: out}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadMuted mutes (muted=true) or unmutes (muted=false) a chat for the
// caller — a per-user marker that syncs across their devices. While set, the
// push fan-out skips every one of their devices for this thread; the muted
// thread's messages still arrive normally. It never affects anyone else, and
// nobody else can see it.
func (s *Server) postThreadMuted(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
		Muted bool   `json:"muted"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	if err := s.db.setThreadMuted(uid, threadID, body.Muted); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadRead advances the caller's read watermark for a thread — "read
// here, read everywhere". last_read_at is the time of the newest message the
// device has shown; when the mark advances, it fans out over WebSocket to the
// caller's OTHER connections so their unread dots clear live. Forward-only (a
// lagging device can't re-light dots), per-user only (never other members),
// and just a timestamp — the server still can't read anything.
func (s *Server) postThreadRead(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token      string `json:"token"`
		LastReadAt int64  `json:"last_read_at"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil || body.LastReadAt <= 0 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	advanced, err := s.db.setThreadRead(uid, threadID, body.LastReadAt)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if advanced {
		out, _ := json.Marshal(wsReadOut{Type: "read", ThreadID: threadID, LastReadAt: body.LastReadAt})
		s.hub.broadcast <- outbound{members: map[string]bool{uid: true}, data: out}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postThreadRemove removes another member from a group. Any member may remove
// any other (matching how adding/renaming work today — the group is flat). Like
// leaving, the key isn't rotated: the server just stops delivering to them.
func (s *Server) postThreadRemove(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token  string `json:"token"`
		UserID string `json:"user_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	threadID := r.PathValue("id")
	if !s.db.threadMember(threadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	// Only groups: removing from a DM would break the one-thread-per-pair model.
	if s.db.threadKind(threadID) != "group" {
		httpError(w, http.StatusBadRequest, "can only remove people from a group")
		return
	}
	if body.UserID == "" || body.UserID == uid || !s.db.threadMember(threadID, body.UserID) {
		httpError(w, http.StatusBadRequest, "not a member of this group") // self uses /leave
		return
	}
	if err := s.db.removeThreadMember(threadID, body.UserID); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Any member can remove in a flat group; only an ADMIN doing it is a
	// moderation action worth the audit log (issue #578) — ordinary member
	// removals would drown the log in group housekeeping.
	if s.db.userRole(uid) == "admin" {
		s.db.addAudit(uid, "thread.removed", body.UserID, threadID, "", "")
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// ---- attachments --------------------------------------------------------

// validBlobID guards path building for a disk-backed blob: ids are randToken
// (base64url), so anything with a path separator, dot, or other character is
// bogus and rejected before it can reach the filesystem.
func validBlobID(id string) bool {
	if id == "" || len(id) > 64 {
		return false
	}
	for _, c := range id {
		if !(c >= 'A' && c <= 'Z' || c >= 'a' && c <= 'z' || c >= '0' && c <= '9' || c == '-' || c == '_') {
			return false
		}
	}
	return true
}

func (s *Server) uploadBlob(w http.ResponseWriter, r *http.Request) {
	if !s.tokenOK(r.URL.Query().Get("token")) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	// Quota (disk backstop): refuse up front when the instance is already at its
	// storage ceiling, so a full disk can't be nudged further.
	if total, err := s.db.blobBytesTotal(); err == nil && total >= s.blobQuota {
		httpError(w, http.StatusInsufficientStorage, "storage full")
		return
	}
	r.Body = http.MaxBytesReader(w, r.Body, s.maxUpload)
	id, err := randToken()
	if err != nil {
		httpError(w, http.StatusInternalServerError, "id error")
		return
	}
	// Stream into a staged store write (never buffer a whole video in RAM);
	// commit under the id only once it's fully written, so a partial/aborted
	// upload is never served. The sha256 rides the same pass — it's the
	// integrity anchor the blob mirror/audit sweeps verify against (#992).
	blob, err := s.db.blobs.create()
	if err != nil {
		log.Printf("upload: blob create: %v", err)
		httpError(w, http.StatusInternalServerError, "storage error")
		return
	}
	hasher := sha256.New()
	size, err := io.Copy(io.MultiWriter(blob, hasher), r.Body)
	if err != nil {
		blob.abort()
		// MaxBytesReader trips here when the body exceeds the cap.
		httpError(w, http.StatusRequestEntityTooLarge, "file too large")
		return
	}
	if size == 0 {
		blob.abort()
		httpError(w, http.StatusBadRequest, "empty upload")
		return
	}
	// Re-check the quota against the real size now we have it.
	if total, err := s.db.blobBytesTotal(); err == nil && total+size > s.blobQuota {
		blob.abort()
		httpError(w, http.StatusInsufficientStorage, "storage full")
		return
	}
	if err := blob.commit(id); err != nil {
		log.Printf("upload: blob commit %s: %v", id, err)
		httpError(w, http.StatusInternalServerError, "storage error")
		return
	}
	// Tag with the (server-known, non-secret) thread id so the blob can be GC'd
	// with its thread / when the referencing message is deleted. Optional: avatar
	// uploads carry no thread.
	if err := s.db.recordBlob(id, r.URL.Query().Get("thread"), size, hex.EncodeToString(hasher.Sum(nil))); err != nil {
		_ = s.db.blobs.remove(id)
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	s.kickBlobMirror() // a fresh blob mirrors promptly while the space is awake
	writeJSON(w, http.StatusOK, map[string]any{"id": id})
}

func (s *Server) getBlobHandler(w http.ResponseWriter, r *http.Request) {
	if !s.tokenOK(r.URL.Query().Get("token")) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	id := r.PathValue("id")
	if !validBlobID(id) {
		http.NotFound(w, r)
		return
	}
	// Blob ids are unique and content is immutable, so it's safe to cache hard.
	w.Header().Set("Cache-Control", "private, max-age=31536000, immutable")
	// nosniff (set globally) stops a mistyped blob being sniffed as HTML; we serve
	// everything as opaque bytes.
	w.Header().Set("Content-Type", "application/octet-stream")
	// Store-backed (all new blobs): stream from the store. ServeContent gives
	// Range support + conditional requests for free (matters for large video),
	// and never loads the whole blob into RAM.
	if f, _, modTime, err := s.db.blobs.open(id); err == nil {
		defer f.Close()
		http.ServeContent(w, r, "", modTime, f)
		return
	}
	// Legacy: bytes still in the DB column (photos uploaded before disk-backing).
	data, err := s.db.legacyBlob(id)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if data == nil {
		http.NotFound(w, r)
		return
	}
	w.Write(data)
}

// ---- link previews ------------------------------------------------------

func (s *Server) unfurl(w http.ResponseWriter, r *http.Request) {
	if !s.tokenOK(r.URL.Query().Get("token")) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	raw := strings.TrimSpace(r.URL.Query().Get("url"))
	u, err := url.Parse(raw)
	if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") || len(raw) > 2048 {
		httpError(w, http.StatusBadRequest, "bad url")
		return
	}
	norm := u.String()
	// The member's own request already carries their Accept-Language; forward
	// it so the page unfurls in their language, not the fetching box's locale.
	lang := previewLang(r.Header.Get("Accept-Language"))

	// Cache hit: serve it now; if it's stale, refresh in the background.
	if pv, ok, _ := s.db.getLinkPreview(norm, lang); ok {
		writeJSON(w, http.StatusOK, pv)
		ttl := int64(previewFreshTTL)
		if !pv.OK {
			ttl = previewFailTTL
		}
		if time.Now().Unix()-pv.FetchedAt > ttl {
			go s.fetchAndCachePreview(norm, lang)
		}
		return
	}
	// Miss: fetch synchronously (de-duped), cache, return.
	writeJSON(w, http.StatusOK, s.fetchAndCachePreview(norm, lang))
}

// previewFlight is one in-progress unfurl; concurrent requests for the same
// URL+language wait on done and share pv rather than fetching again.
type previewFlight struct {
	done chan struct{}
	pv   LinkPreview
}

// fetchAndCachePreview fetches+stores a preview, ensuring only one fetch per
// URL+language runs at a time. Concurrent callers WAIT for that fetch and get
// its result — answering them with an empty stub instead is why a recipient
// (whose render of a just-posted link races the poster's synchronous fetch)
// never saw a card the poster did. The wait is bounded by fetchOG's timeout.
func (s *Server) fetchAndCachePreview(norm, lang string) LinkPreview {
	flightKey := previewCacheKey(lang, norm)
	f := &previewFlight{done: make(chan struct{})}
	if cur, busy := s.inflight.LoadOrStore(flightKey, f); busy {
		flight := cur.(*previewFlight)
		<-flight.done
		return flight.pv
	}
	defer func() {
		s.inflight.Delete(flightKey)
		close(f.done)
	}()

	pv, err := fetchOG(norm, lang)
	if err != nil {
		pv = LinkPreview{URL: norm, OK: false}
	}
	pv.URL = norm
	pv.FetchedAt = time.Now().Unix()
	_ = s.db.putLinkPreview(pv, lang)
	f.pv = pv
	return pv
}

// ---- key-invites (invite redesign) --------------------------------------

// createKeyInvite stores a client-wrapped group key (the admin's browser did the
// wrapping; the server never sees the secret or plaintext key). Creates a user
// when no user_id is given (re-issue passes an existing user_id).
// getBotConfig returns the caller's own agent config. The sidecar fetches this
// with its device token to pick up console-managed model/prompt/docs; it's scoped
// to the caller's user, so a bot only ever reads its own config.
func (s *Server) getBotConfig(w http.ResponseWriter, r *http.Request) {
	token := r.URL.Query().Get("token")
	if !s.tokenOK(token) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	uid, ok := s.db.deviceTokenUser(token)
	if !ok {
		writeJSON(w, http.StatusOK, BotConfig{AIEnabled: s.db.aiEnabled()})
		return
	}
	c, _, err := s.db.botConfig(uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	c.AIEnabled = s.db.aiEnabled()
	writeJSON(w, http.StatusOK, c)
}

// declareBotKind lets a sidecar self-report its identity's kind — "ai" (LLM-backed:
// what it reads is sent to a model provider) or "bot" (deterministic: nothing
// leaves the server). Authed by the bot's OWN device token, not the admin token:
// it can only set its own kind, and only for an agent. This is why Eleven can
// badge BOT when it runs commands-only and AI once its model brain is live —
// the sidecar knows which, and the badge follows the truth.
func (s *Server) declareBotKind(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
		Kind  string `json:"kind"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok || !s.db.isAgent(uid) {
		httpError(w, http.StatusBadRequest, "not a bot")
		return
	}
	if body.Kind != "ai" && body.Kind != "bot" {
		httpError(w, http.StatusBadRequest, "bad kind")
		return
	}
	if err := s.db.setBotKind(uid, body.Kind); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

func (s *Server) createKeyInvite(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	var body struct {
		Label     string `json:"label"`
		UserID    string `json:"user_id"`
		ID        string `json:"id"`
		Wrapped   string `json:"wrapped"`
		ClaimHash string `json:"claim_hash"` // proof-of-secret for claiming (see deriveInvite)
		Expires   int64  `json:"expires"`
		Agent     bool   `json:"agent"` // mark the invited user as a bot (badge only)
		// Agent config (only when Agent) — the sidecar applies these.
		Model        string `json:"model"`
		SystemPrompt string `json:"system_prompt"`
		Docs         string `json:"docs"`
		// Helpers catalog metadata (only when Agent): the one-line blurb members
		// see, and whether the bot shows in everyone's Helpers list (docs/bots.md).
		Description string `json:"description"`
		Available   bool   `json:"available_to_members"`
		// Listen mode (only when Agent): when the bot replies in groups —
		// ""/"mention" = @mention only (default), "name" = also on its bare name.
		Listen string `json:"listen"`
		// GrantsAdmin marks a setup invite: its claimer becomes an admin. Minted by
		// add-instance for a fresh instance's first user (and available to admins
		// for promoting someone at invite time). See docs/conversational-onboarding.md.
		GrantsAdmin bool `json:"grants_admin"`
		// HooksService marks the hooks sidecar's service identity invite
		// (add-hooks mints it — hooks.go, docs/webhooks.md): the claimer is
		// recorded in config so webhook creation knows which pubkey to seal
		// definitions to. Not an AI bot, so it bypasses the bots gate.
		HooksService bool `json:"hooks_service"`
		// TierID makes this a COHORT invite: the claimer is assigned that
		// access level on first-device claim ('invite' source). Admin-minted
		// only, which is what keeps level assignment an admin power.
		TierID string `json:"tier_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// Wrapped is optional now: a fresh-person invite carries no key (the joiner
	// generates their own user keypair). Only an add-device invite wraps the
	// user's private key. See docs/threads-and-dms.md.
	if body.ID == "" || len(body.ID) > 200 || len(body.Wrapped) > 4096 || len(body.Description) > 300 ||
		body.ClaimHash == "" || len(body.ClaimHash) > 128 {
		httpError(w, http.StatusBadRequest, "missing id")
		return
	}
	// The bots gate stops NEW bot identities being minted (checked before the
	// user row exists, so a rejected mint leaves nothing behind); bots already
	// on the roster keep running — the admin retires those by removal. The
	// hooks service identity is exempt: it's integration plumbing (no AI, no
	// conversations), gated instead by webhooks being admin-only.
	if body.Agent && !body.HooksService && !s.db.botsEnabled() {
		httpError(w, http.StatusForbidden, "bots are turned off for this space")
		return
	}
	userID := body.UserID
	if userID == "" {
		// A person gets no plaintext name — they publish theirs encrypted (under the
		// instance key) after joining, and the pre-fill name rides in the invite
		// link's #fragment. Only bots keep an admin-authored plaintext label.
		newLabel := ""
		if body.Agent {
			newLabel = strings.TrimSpace(body.Label)
		}
		id, err := s.db.createUser(newLabel)
		if err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		userID = id
	} else if !s.db.userExists(userID) {
		httpError(w, http.StatusBadRequest, "unknown user")
		return
	}
	if body.Agent {
		if body.Listen != "" && body.Listen != "mention" && body.Listen != "name" {
			httpError(w, http.StatusBadRequest, "bad listen")
			return
		}
		if err := s.db.setUserAgent(userID); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		if err := s.db.setBotConfig(userID, body.Model, body.SystemPrompt, body.Docs, body.Listen, strings.TrimSpace(body.Description), body.Available); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		if body.HooksService {
			// Record which identity webhook definitions seal to, and badge it
			// distinctly from conversational bots. Last mint wins — re-running
			// add-hooks after a lost session repoints creation at the fresh
			// identity (stale defs sealed to the old key simply stop deploying).
			if err := s.db.setConfig(hooksServiceUserKey, userID); err != nil {
				httpError(w, http.StatusInternalServerError, "db error")
				return
			}
			if err := s.db.setBotKind(userID, "webhook"); err != nil {
				httpError(w, http.StatusInternalServerError, "db error")
				return
			}
		}
	}
	if body.TierID != "" && !s.db.tierExists(body.TierID) {
		httpError(w, http.StatusBadRequest, "bad access level")
		return
	}
	if err := s.db.createKeyInvite(body.ID, userID, body.Wrapped, body.ClaimHash, body.Expires); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if body.GrantsAdmin {
		if err := s.db.setInviteGrantsAdmin(body.ID); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.TierID != "" {
		if err := s.db.setInviteTier(body.ID, body.TierID); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "user_id": userID})
}

// getKeyInvite returns the wrapped key for an unused, unexpired invite. The id is
// the client-derived handle; without the secret the wrapped blob is useless.
func (s *Server) getKeyInvite(w http.ResponseWriter, r *http.Request) {
	ki, found, err := s.db.getKeyInvite(r.PathValue("id"))
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	ok := found && !ki.Used && !ki.Expired
	resp := map[string]any{"ok": ok}
	if ok {
		resp["wrapped"] = ki.Wrapped
		// A user invite drops the joiner into a pending DM. The client uses this to
		// (a) re-wrap the DM key to itself and (b) know an existing member can adopt.
		resp["dm"] = ki.ThreadID != ""
		// A setup invite lands chat-first: the join page skips its name form (the
		// setup conversation asks instead). Only link-holders can derive the id, so
		// this flags nothing to anyone who couldn't claim it anyway.
		resp["grants_admin"] = ki.GrantsAdmin
		// The space's description, so the welcome card can say what this place is
		// before the joiner holds any key. Only link-holders can derive the invite
		// id, so this stays "invited people only" — it's never on the public read.
		if d := s.db.getGroupDescription(); d != "" {
			resp["description"] = d
		}
		// Sealed branding: the invite link's #fragment carries B, so the join
		// card decrypts the full branding set (name, description, avatar alt)
		// from this blob instead of the plaintext fields above.
		if s.db.brandingSealed() {
			blob, _, _ := s.db.getConfig("branding_blob")
			salt, _, _ := s.db.getConfig("branding_salt")
			resp["branding_blob"] = blob
			resp["branding_salt"] = salt
		}
		// A cohort invite says which access level the joiner lands in — the
		// level NAME is branding-class by design (plaintext space policy), and
		// like the description it's served to link-holders only.
		if ki.TierID != "" {
			if n := s.db.tierName(ki.TierID); n != "" {
				resp["tier_name"] = n
			}
		}
		// The suggested pre-fill name is NOT returned here — it rides in the invite
		// link's #fragment (never sent to the server), so the server never sees it.
	}
	writeJSON(w, http.StatusOK, resp)
}

// claimKeyInvite marks the invite used (single-use) and mints a device token for
// ongoing auth. The secret never reaches the server — only this claim does. For a
// user invite, `wrapped` is the pending DM's key wrapped to the joiner's own new
// public key; we store it so they can read the DM straight away, and return the
// thread id so the client opens it first.
func (s *Server) claimKeyInvite(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Wrapped     string `json:"wrapped"`
		ClaimSecret string `json:"claim_secret"`
	}
	json.NewDecoder(r.Body).Decode(&body)
	if len(body.Wrapped) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	id := r.PathValue("id")
	// Grab the pending DM (if any) before the claim consumes the invite.
	ki, _, _ := s.db.getKeyInvite(id)
	// No plaintext device label: the joiner's screen name is never sent to the
	// server — they publish it encrypted (POST /api/label) after joining.
	tok, ok, err := s.db.claimKeyInvite(id, "", body.Wrapped, body.ClaimSecret)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if !ok {
		httpError(w, http.StatusForbidden, "invite unavailable")
		return
	}
	resp := map[string]any{"ok": true, "token": tok}
	if ki.ThreadID != "" {
		resp["thread_id"] = ki.ThreadID
	}
	writeJSON(w, http.StatusOK, resp)
}

func (s *Server) listUsers(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	users, err := s.db.listUsers()
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"users": users})
}

// getAdminBotConfig returns a bot's full console-managed config (persona,
// model, docs + Helpers-catalog metadata) so the admin can edit it after
// creation. 400s for a non-agent — people don't have bot config.
func (s *Server) getAdminBotConfig(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	id := r.PathValue("id")
	if !s.db.isAgent(id) {
		httpError(w, http.StatusBadRequest, "not a bot")
		return
	}
	c, _, err := s.db.fullBotConfig(id) // ok=false → zero-value config, still editable
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, c)
}

// setAdminBotConfig updates a bot's config in place. The sidecar re-pulls its
// config on every reconnect (~a minute), so edits take effect without a
// redeploy; catalog changes (description/availability) show in rosters
// immediately.
func (s *Server) setAdminBotConfig(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	id := r.PathValue("id")
	if !s.db.isAgent(id) {
		httpError(w, http.StatusBadRequest, "not a bot")
		return
	}
	var body FullBotConfig
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if len(body.Description) > 300 {
		httpError(w, http.StatusBadRequest, "description too long")
		return
	}
	if body.Listen != "" && body.Listen != "mention" && body.Listen != "name" {
		httpError(w, http.StatusBadRequest, "bad listen")
		return
	}
	if len(body.Welcome) > 2000 {
		httpError(w, http.StatusBadRequest, "welcome too long")
		return
	}
	if err := s.db.setBotConfig(id, body.Model, body.SystemPrompt, body.Docs, body.Listen, strings.TrimSpace(body.Description), body.Available); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Welcome text is a narrow upsert (see setBotWelcome) so it composes with the
	// config write above without widening setBotConfig's signature.
	if err := s.db.setBotWelcome(id, strings.TrimSpace(body.Welcome)); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// renameUser changes a user's roster label (admin roster management — e.g.
// renaming a bot after its default changes). Display only: keys and history
// are untouched, and messages keep the name they were sent under (it's inside
// the encrypted payload, which the server can't rewrite anyway).
func (s *Server) renameUser(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	var body struct {
		Label string `json:"label"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	label := strings.TrimSpace(body.Label)
	if label == "" || len(label) > 60 {
		httpError(w, http.StatusBadRequest, "bad label")
		return
	}
	// Only bots have an admin-settable plaintext name. A person's name is encrypted
	// under the instance key and set by the member themselves (POST /api/label), so
	// the admin can't (and shouldn't) rename people.
	if !s.db.isAgent(r.PathValue("id")) {
		httpError(w, http.StatusBadRequest, "people set their own name")
		return
	}
	if err := s.db.setUserLabel(r.PathValue("id"), label); err == sql.ErrNoRows {
		httpError(w, http.StatusBadRequest, "unknown user")
		return
	} else if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// removeUser deletes a person from the instance (admin roster management).
func (s *Server) removeUser(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	if err := s.db.removeUser(r.PathValue("id")); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Removal is a moderation action — it lands in the audit log (issue #578).
	s.db.addAudit(s.adminActor(r), "member.removed", r.PathValue("id"), "", "", "")
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// banUser removes a member AND remembers their public key (issue #578), so
// the same key can't re-register through any later invite — admin, member, or
// cohort. removeUser's sweep already covers their content, tokens, queued
// scheduled messages, and level memberships.
func (s *Server) banUser(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	uid := r.PathValue("id")
	if !s.db.userExists(uid) {
		httpError(w, http.StatusBadRequest, "no such user")
		return
	}
	// Capture the key BEFORE removal deletes the row; a keyless member (a
	// pending invitee) has nothing durable to ban — removal alone covers them.
	pub := s.db.userPublicKey(uid)
	if err := s.db.removeUser(uid); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if pub != "" {
		if err := s.db.addBan(pub, uid, s.adminActor(r)); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	s.db.addAudit(s.adminActor(r), "member.banned", uid, "", "", "")
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// adminActor resolves who performed an admin action for the audit log: the
// admin member's uid when the bearer is a device token, else "console" (the
// break-glass admin token has no member identity).
func (s *Server) adminActor(r *http.Request) string {
	const p = "Bearer "
	h := r.Header.Get("Authorization")
	if strings.HasPrefix(h, p) {
		if uid, ok := s.db.deviceTokenUser(strings.TrimSpace(strings.TrimPrefix(h, p))); ok {
			return uid
		}
	}
	return "console"
}

// postReport files a report (issue #578): queue metadata for the server, the
// report's words sealed to each admin's public key by the reporter's client.
// Reports are testimony — the server can't verify them, and the UI says so.
func (s *Server) postReport(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token      string `json:"token"`
		ReportedID string `json:"reported_id"`
		ThreadID   string `json:"thread_id"`
		Blobs      []struct {
			AdminID string `json:"admin_id"`
			Blob    string `json:"blob"`
		} `json:"blobs"`
	}
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	if body.ReportedID == "" || body.ReportedID == uid || !s.db.userExists(body.ReportedID) {
		httpError(w, http.StatusBadRequest, "bad reported_id")
		return
	}
	if body.ThreadID != "" && !s.db.threadMember(body.ThreadID, uid) {
		httpError(w, http.StatusForbidden, "not a thread member")
		return
	}
	// The report-abuse brake (content-blind): filing is cheap for a person,
	// expensive as a flood. Repeat-filer counts also surface in the queue.
	if s.db.reportsSince(uid, time.Now().Add(-time.Hour).Unix()) >= 5 {
		httpError(w, http.StatusTooManyRequests, "too many reports — try again later")
		return
	}
	// Every blob must be addressed to a current admin, and there must be at
	// least one — a report nobody can read helps no one.
	if len(body.Blobs) == 0 || len(body.Blobs) > 32 {
		httpError(w, http.StatusBadRequest, "bad blobs")
		return
	}
	blobs := map[string]string{}
	for _, b := range body.Blobs {
		if b.Blob == "" || len(b.Blob) > 64*1024 || s.db.userRole(b.AdminID) != "admin" {
			httpError(w, http.StatusBadRequest, "bad blobs")
			return
		}
		blobs[b.AdminID] = b.Blob
	}
	id, err := s.db.createReport(uid, body.ReportedID, body.ThreadID, blobs)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Nudge admins' live clients so the queue updates without a reload.
	admins, _ := s.db.adminUserIDs()
	if len(admins) > 0 {
		set := map[string]bool{}
		for _, a := range admins {
			set[a] = true
		}
		out, _ := json.Marshal(map[string]any{"type": "report_filed", "report_id": id})
		s.hub.broadcast <- outbound{members: set, data: out}
	}
	// And their away devices, throttled — one push per burst, not one per report.
	go s.pushReportNotice()
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "id": id})
}

// adminReports lists the moderation queue. The metadata is admin-auth like the
// rest of /api/admin; the content blob in each row is the CALLER's sealed copy
// (only an admin member's client holds the key to open it — the break-glass
// console token sees metadata only, by construction).
func (s *Server) adminReports(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	actor := s.adminActor(r)
	reports, err := s.db.listReports(actor)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"reports": reports})
}

// resolveReportHandler records a report's outcome (the action itself — remove,
// warn, demote — runs through its own endpoint first; this closes the loop).
func (s *Server) resolveReportHandler(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	var body struct {
		Action string `json:"action"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	switch body.Action {
	case "dismissed", "warned", "removed_thread", "removed_space", "demoted", "banned":
	default:
		httpError(w, http.StatusBadRequest, "bad action")
		return
	}
	id := r.PathValue("id")
	ok, err := s.db.resolveReport(id, body.Action, s.adminActor(r))
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if !ok {
		httpError(w, http.StatusConflict, "already resolved")
		return
	}
	s.db.addAudit(s.adminActor(r), "report.resolved", "", "", id, body.Action)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// adminWarn records that a warning was issued (issue #578). The warning's
// words travel as an ordinary E2EE DM from the admin's client with a `warn`
// flag inside the ciphertext — the server records only that the rung was used.
func (s *Server) adminWarn(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	var body struct {
		UserID   string `json:"user_id"`
		ReportID string `json:"report_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil || body.UserID == "" {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.db.userExists(body.UserID) {
		httpError(w, http.StatusBadRequest, "no such user")
		return
	}
	s.db.addAudit(s.adminActor(r), "member.warned", body.UserID, "", body.ReportID, "")
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// reportPushCooldown is the report notification's quiet window: the first
// report of a burst notifies at once; everything else inside the window rides
// silently (the notification's job is "go look", and each one carries the
// current open count, so nothing is lost to the throttle).
const reportPushCooldown = 15 * time.Minute

// pushReportNotice tells the space's admins a report arrived — at most once
// per quiet window. The words are server-composed metadata ("N waiting"),
// never report content: the same plaintext-operational class as the changelog
// announcement, delivered the same two ways (Web Push + APNs) and shown even
// while the app is open (there's no in-app badge to lean on). Returns whether
// this call was the one that notified, for the throttle test.
func (s *Server) pushReportNotice() bool {
	s.reportPushMu.Lock()
	if time.Since(s.lastReportPush) < reportPushCooldown {
		s.reportPushMu.Unlock()
		return false
	}
	s.lastReportPush = time.Now()
	s.reportPushMu.Unlock()

	admins, err := s.db.adminUserIDs()
	if err != nil || len(admins) == 0 {
		return true // throttle consumed; nobody to tell
	}
	recipients := make(map[string]bool, len(admins))
	for _, id := range admins {
		recipients[id] = true
	}
	n := s.db.openReportCount()
	title := "New report in " + s.db.getGroupName()
	body := "A report is waiting for review in the Admin panel."
	if n > 1 {
		body = fmt.Sprintf("%d reports are waiting for review in the Admin panel.", n)
	}
	payload, _ := json.Marshal(map[string]any{"report": true, "title": title, "body": body})
	sent := s.sendToRecipients(payload, "report", "", false, recipients)
	sent += s.apnsAnnounce(title, body, recipients)
	// The same once-per-burst signal to LIVE admin sessions: each open device
	// lights the Admin thread's dot from this frame directly (a self-posted
	// bubble couldn't — your own messages never light your dots), and one
	// visible session writes the durable line into the Admin stream.
	frame, _ := json.Marshal(map[string]any{"type": "report_notice", "n": n})
	s.hub.broadcast <- outbound{members: recipients, data: frame}
	log.Printf("reports: notified admins (%d subscription(s), %d open)", sent, n)
	return true
}

// adminAudit pages the moderation audit log, newest first.
func (s *Server) adminAudit(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	before, _ := strconv.ParseInt(r.URL.Query().Get("before"), 10, 64)
	limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
	entries, err := s.db.listAudit(before, limit)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"entries": entries})
}

// createDeviceInvite lets a member mint a fresh invite for their OWN account (to
// add another device), authenticated by their existing token. The browser wraps
// the key it already holds; the server stays blind. Ties to the device token's
// user, or creates one for a legacy member.
func (s *Server) createDeviceInvite(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		ID        string `json:"id"`
		Wrapped   string `json:"wrapped"`
		ClaimHash string `json:"claim_hash"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	if body.ID == "" || body.Wrapped == "" || len(body.ID) > 200 || len(body.Wrapped) > 4096 ||
		body.ClaimHash == "" || len(body.ClaimHash) > 128 {
		httpError(w, http.StatusBadRequest, "missing id/wrapped")
		return
	}
	userID, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		// Legacy member (joined via an old #k= link) — give them a user now. No
		// plaintext name: they republish it encrypted (POST /api/label) on next load.
		id, err := s.db.createUser("")
		if err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		userID = id
	}
	if err := s.db.createKeyInvite(body.ID, userID, body.Wrapped, body.ClaimHash, 0); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// postUserInvite lets a member invite a brand-new person straight into a DM.
// Ordinary members are gated by the "users can invite" admin setting (off by
// default); an admin may always invite. The browser
// generates the DM key and hands us only wrapped blobs: `wrapped` is the key
// encrypted to the invite secret (so the joiner recovers it), `self_wrapped` is it
// wrapped to the inviter's own public key. With no thread_id we create the pending
// invitee + DM + invite in one go; with a thread_id we re-issue a fresh link for an
// existing pending invitee (a lost/expired link, same chat). The server stays blind.
func (s *Server) postUserInvite(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token       string `json:"token"`
		LabelBlob   string `json:"label_blob"` // invitee's name, encrypted to the instance key by the inviter
		ID          string `json:"id"`
		Wrapped     string `json:"wrapped"`
		SelfWrapped string `json:"self_wrapped"`
		ClaimHash   string `json:"claim_hash"`
		ThreadID    string `json:"thread_id"`
		// TierID makes this a cohort invite (claimer lands in the level on
		// first-device claim). Role-admins only — level assignment is an
		// admin power, so a member invite can't smuggle anyone in.
		TierID string `json:"tier_id"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	// The "members can invite" toggle governs ordinary members; an admin can
	// always invite. Without the bypass the person who just set the space up
	// couldn't bring anyone in without flipping the toggle in the admin
	// console — a path we're sunsetting.
	if !s.db.usersCanInvite() && s.db.userRole(uid) != "admin" {
		httpError(w, http.StatusForbidden, "inviting is turned off")
		return
	}
	// The invite-minting brake (issue #578): content-blind, admin-exempt —
	// nobody human mints twenty invites in a day by hand.
	if s.db.userRole(uid) != "admin" && !s.brake().invites.allow(uid) {
		httpError(w, http.StatusTooManyRequests, "that's a lot of invites — try again tomorrow")
		return
	}
	if body.ID == "" || len(body.ID) > 200 || body.Wrapped == "" || len(body.Wrapped) > 4096 ||
		body.ClaimHash == "" || len(body.ClaimHash) > 128 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}

	// Re-send: a fresh link for an existing pending invitee (same DM). Only the
	// inviter (a member of that pending DM) may, and only while it's still pending.
	if body.ThreadID != "" {
		if !s.db.threadMember(body.ThreadID, uid) || s.db.threadKind(body.ThreadID) != "dm" {
			httpError(w, http.StatusForbidden, "not your pending chat")
			return
		}
		invitee, found := s.db.otherThreadMember(body.ThreadID, uid)
		if !found {
			httpError(w, http.StatusBadRequest, "no invitee")
			return
		}
		// Only re-send while they're still a keyless placeholder. Once they've joined
		// (registered a public key), a fresh claimable invite for them would be an
		// account-takeover vector — and there's nothing to re-send anyway.
		if s.db.userPublicKey(invitee) != "" {
			httpError(w, http.StatusBadRequest, "they've already joined")
			return
		}
		if err := s.db.createKeyInviteWithThread(body.ID, invitee, body.Wrapped, body.ThreadID, body.ClaimHash, 0); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "thread_id": body.ThreadID, "user_id": invitee})
		return
	}

	if body.LabelBlob == "" || len(body.LabelBlob) > 4096 || body.SelfWrapped == "" || len(body.SelfWrapped) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// The flat-group rule applied to levels: membership is the power to
	// extend membership. Anyone may cohort-invite into a level THEY belong to
	// (they hold its key already — the server can't pretend otherwise);
	// admins may mint for any level. Nobody mints access they don't hold.
	if body.TierID != "" && !s.db.tierExists(body.TierID) {
		httpError(w, http.StatusBadRequest, "bad access level")
		return
	}
	if body.TierID != "" && s.db.userRole(uid) != "admin" && !s.db.tierMember(body.TierID, uid) {
		httpError(w, http.StatusForbidden, "not in that level")
		return
	}
	threadID, inviteeID, err := s.db.createUserInvite(uid, body.ID, body.LabelBlob, body.Wrapped, body.SelfWrapped, body.ClaimHash, 0)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if body.TierID != "" {
		if err := s.db.setInviteTier(body.ID, body.TierID); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "thread_id": threadID, "user_id": inviteeID})
}

// adoptKeyInvite handles a user invite opened by someone who is ALREADY a member on
// this device: their existing account joins the pending DM (deduped if they already
// share one), instead of the placeholder becoming a new user. `wrapped` is the DM
// key wrapped to their existing public key. Auth is their own device token.
func (s *Server) adoptKeyInvite(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token       string `json:"token"`
		Wrapped     string `json:"wrapped"`
		ClaimSecret string `json:"claim_secret"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	// Check if this is an admin invite (no wrapped payload needed for admin invites).
	id := r.PathValue("id")
	ki, found, err := s.db.getKeyInvite(id)
	if err != nil || !found {
		httpError(w, http.StatusForbidden, "invite unavailable")
		return
	}
	if ki.GrantsAdmin {
		// Admin invite: promote the existing user to admin.
		if ok, err := s.db.adoptAdminInvite(id, uid, body.ClaimSecret); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		} else if !ok {
			httpError(w, http.StatusForbidden, "invite unavailable")
			return
		}
		// Unlike a fresh joiner's first key (which fires "joined"), promoting an
		// EXISTING member to admin touches no roster field a client watches for —
		// so every other open tab kept treating this user as a non-admin (e.g.
		// when building a report's admin-encryption list) until something else
		// happened to trigger a reload. Tell open tabs now.
		out, _ := json.Marshal(map[string]any{"type": "role_changed", "user_id": uid})
		s.hub.broadcast <- outbound{data: out}
		writeJSON(w, http.StatusOK, map[string]any{"ok": true})
		return
	}
	// DM invite: wrapped key is required.
	if body.Wrapped == "" || len(body.Wrapped) > 4096 {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	threadID, ok, err := s.db.adoptUserInvite(id, uid, body.Wrapped, body.ClaimSecret)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if !ok {
		httpError(w, http.StatusForbidden, "invite unavailable")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "thread_id": threadID})
}

// cancelInvite tears down a pending DM whose invitee never joined (thread, keys,
// members, placeholder, invite). Only the inviter may, and only while it's pending.
func (s *Server) cancelInvite(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token string `json:"token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	uid, ok := s.db.deviceTokenUser(body.Token)
	if !ok {
		httpError(w, http.StatusForbidden, "no user for token")
		return
	}
	done, err := s.db.cancelUserInvite(r.PathValue("id"), uid)
	if err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if !done {
		httpError(w, http.StatusBadRequest, "not a pending invite")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// ---- admin API ----------------------------------------------------------

func (s *Server) requireAdmin(w http.ResponseWriter, r *http.Request) bool {
	const p = "Bearer "
	h := r.Header.Get("Authorization")
	if strings.HasPrefix(h, p) {
		bearer := strings.TrimSpace(strings.TrimPrefix(h, p))
		// Two ways in: the admin token (break-glass / provisioning), or a member's
		// own device token when their user holds the admin role — so the in-app
		// admin surface works with the session it already has. Either way this is
		// authorisation only; no key material rides on it.
		if s.db.checkAdmin(bearer) {
			return true
		}
		if uid, ok := s.db.deviceTokenUser(bearer); ok && s.db.userRole(uid) == "admin" {
			return true
		}
	}
	httpError(w, http.StatusUnauthorized, "admin auth required")
	return false
}

// ---- push notifications -------------------------------------------------

func (s *Server) getVAPID(w http.ResponseWriter, r *http.Request) {
	writeJSON(w, http.StatusOK, map[string]any{"publicKey": s.vapidPub})
}

func (s *Server) subscribePush(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token        string `json:"token"`
		Subscription struct {
			Endpoint string `json:"endpoint"`
			Keys     struct {
				P256dh string `json:"p256dh"`
				Auth   string `json:"auth"`
			} `json:"keys"`
		} `json:"subscription"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// Only valid participants (invite or device token) may register for push.
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "invalid invite")
		return
	}
	if body.Subscription.Endpoint == "" {
		httpError(w, http.StatusBadRequest, "missing subscription")
		return
	}
	// The endpoint is attacker-controlled and the server POSTs to it; reject
	// anything that isn't a plain https URL so it can't be aimed at our own
	// network (SSRF). The pushClient dialer enforces the resolved-IP check.
	if err := validatePushEndpoint(body.Subscription.Endpoint); err != nil {
		httpError(w, http.StatusBadRequest, "bad subscription endpoint")
		return
	}
	uid, _ := s.db.deviceTokenUser(body.Token) // "" for a legacy (non-device) token
	if err := s.db.addSubscription(PushSub{
		Endpoint: body.Subscription.Endpoint,
		Token:    body.Token,
		P256dh:   body.Subscription.Keys.P256dh,
		Auth:     body.Subscription.Keys.Auth,
		UserID:   uid,
	}); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

func (s *Server) unsubscribePush(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token    string `json:"token"`
		Endpoint string `json:"endpoint"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// Require a valid participant token and only remove that token's own
	// subscription — otherwise anyone who learned an endpoint could silently
	// unsubscribe (deny notifications to) someone else's device.
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	if body.Endpoint != "" {
		_ = s.db.deleteOwnSubscription(body.Endpoint, body.Token)
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

func (s *Server) testPush(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "sent": s.sendTestPush()})
}

// serveSW serves the service worker from the root path so its scope covers the app.
func (s *Server) serveSW(w http.ResponseWriter, r *http.Request) {
	b, err := webFS.ReadFile("web/static/sw.js")
	if err != nil {
		http.NotFound(w, r)
		return
	}
	w.Header().Set("Content-Type", "application/javascript; charset=utf-8")
	w.Header().Set("Cache-Control", "no-cache")
	w.Write(b)
}

// serveManifest generates the PWA manifest with the configured group name, so the
// Home Screen / install name matches the chat.
func (s *Server) serveManifest(w http.ResponseWriter, r *http.Request) {
	name := s.db.getGroupName()
	w.Header().Set("Content-Type", "application/manifest+json; charset=utf-8")
	json.NewEncoder(w).Encode(map[string]any{
		"name":             name,
		"short_name":       name,
		"description":      "A private, end-to-end encrypted group chat",
		"start_url":        "/",
		"scope":            "/",
		"display":          "standalone",
		"background_color": "#f6f7fb",
		"theme_color":      "#5b6cff",
		"icons": []map[string]any{
			{"src": "/static/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any"},
			{"src": "/static/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable"},
		},
	})
}

// ---- group name ---------------------------------------------------------

func (s *Server) getGroup(w http.ResponseWriter, r *http.Request) {
	// `avatar` lets clients decide whether to render /api/server-avatar without a
	// speculative image fetch (used by the join cards, home Save-passkey card, and
	// the native add-chat screens).
	_, _, _, hasAvatar := s.db.getInstanceAvatar()
	// name_set distinguishes an admin-chosen name from the compiled-in default,
	// so first-run setup asks for a name instead of offering "keep the default".
	out := map[string]any{"name": s.db.getGroupName(), "name_set": s.db.groupNameSet(), "avatar": hasAvatar}
	if hasAvatar {
		// The photo's alt text (plaintext branding, admin-set) — clients set it
		// on every rendering of /api/server-avatar, join cards included.
		alt, _, _ := s.db.getConfig("server_avatar_alt")
		out["avatar_alt"] = alt
	}
	// Sealed branding (docs/no-plaintext.md): the flag is public (join cards
	// need it to skip rendering ciphertext), but the blob + salt are NOT —
	// members get them below, and invitees get them via their unguessable
	// invite id (getKeyInvite). Serving ciphertext to bare visitors would only
	// widen the old plaintext gating: anyone could start the offline
	// brute-force, and any past link-holder could open the admin
	// name/email — a tier the plaintext era kept members-only. `name` above
	// already fell back to the compiled-in default (seal clears group_name).
	if s.db.brandingSealed() {
		out["sealed"] = true
	}
	// The administrator identity is member-only, not public branding: this
	// endpoint is also the unauthenticated onboarding read, so only add the
	// admin's name + contact email when a valid member token is presented.
	if s.tokenOK(r.URL.Query().Get("token")) {
		// Members get the sealed branding set plus the branding key wrapped
		// under the instance key, so nobody has to re-visit an invite link.
		if s.db.brandingSealed() {
			blob, _, _ := s.db.getConfig("branding_blob")
			salt, _, _ := s.db.getConfig("branding_salt")
			out["branding_blob"] = blob
			out["branding_salt"] = salt
			ks, _, _ := s.db.getConfig("branding_key_sealed")
			out["branding_key_sealed"] = ks
		}
		out["admin_name"] = s.db.getAdminName()
		out["admin_email"] = s.db.getAdminEmail()
		// The space description is member-gated like the admin identity: this
		// endpoint is also the public onboarding read, and invitees get the
		// description via their (unguessable) invite id instead — see getKeyInvite.
		out["description"] = s.db.getGroupDescription()
		// The feature gates ride the member read too — the native apps consult
		// them to hide entry points (the gated endpoints enforce regardless).
		out["ai_enabled"] = s.db.aiEnabled()
		out["bots_enabled"] = s.db.botsEnabled()
		out["apps_enabled"] = s.db.appsEnabled()
		out["member_apps_enabled"] = s.db.memberAppsEnabled()
		// The fetch service this instance prefers for unfurls (docs/fetch.md).
		// The web page gets it injected (__FETCH_URL__); native reads it here.
		out["fetch_url"] = s.fetchURL
	}
	writeJSON(w, http.StatusOK, out)
}

// ---- server avatar (instance branding photo) ----------------------------
//
// A per-instance branding photo, admin-set and served in the clear like the
// group name — it must render before any key exists (onboarding) and to the
// instance-agnostic home server, so it can't be E2E-encrypted. Never user
// content; message/profile-photo E2E is untouched.

// getServerAvatar serves the branding photo unauthenticated (like getGroup). 404
// when unset so clients fall back to the built-in app icon.
func (s *Server) getServerAvatar(w http.ResponseWriter, r *http.Request) {
	data, mime, updatedAt, ok := s.db.getInstanceAvatar()
	if !ok {
		http.NotFound(w, r)
		return
	}
	// ETag from the update stamp so an admin's change propagates but unchanged
	// photos revalidate cheaply. X-Content-Type-Options: nosniff is set globally.
	etag := fmt.Sprintf(`"%d"`, updatedAt)
	if match := r.Header.Get("If-None-Match"); match == etag {
		w.WriteHeader(http.StatusNotModified)
		return
	}
	w.Header().Set("Content-Type", mime)
	w.Header().Set("ETag", etag)
	w.Header().Set("Cache-Control", "public, max-age=60, must-revalidate")
	w.Write(data)
}

// setServerAvatar (admin) stores a new branding photo. The body is the raw image
// bytes; the type is sniffed from the content, not trusted from a header.
// While branding is sealed, photos go through sealBranding instead (the bytes
// here would be readable at rest).
func (s *Server) setServerAvatar(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	if !s.requireUnsealed(w) {
		return
	}
	r.Body = http.MaxBytesReader(w, r.Body, maxServerAvatarBytes)
	data, err := io.ReadAll(r.Body)
	if err != nil {
		httpError(w, http.StatusRequestEntityTooLarge, "image too large (max 1 MB)")
		return
	}
	if len(data) == 0 {
		httpError(w, http.StatusBadRequest, "empty upload")
		return
	}
	// Sniff the real type rather than trusting the client. Only raster images we
	// know are safe to serve inline — no SVG (it can carry script).
	mime := http.DetectContentType(data)
	switch mime {
	case "image/png", "image/jpeg", "image/webp":
	default:
		httpError(w, http.StatusUnsupportedMediaType, "must be a PNG, JPEG, or WebP image")
		return
	}
	if err := s.db.setInstanceAvatar(data, mime, time.Now().Unix()); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	// Optional alt text rides as a query param (the body is the raw image).
	// Plaintext branding like the photo itself — it must be readable on keyless
	// surfaces (the join card). A new photo always resets it (empty clears).
	if err := s.db.setConfig("server_avatar_alt", trimAltText(r.URL.Query().Get("alt"))); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// deleteServerAvatar (admin) clears the branding photo (reverts to the app icon).
func (s *Server) deleteServerAvatar(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	if err := s.db.clearInstanceAvatar(); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	_ = s.db.setConfig("server_avatar_alt", "") // the alt text goes with the photo
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

func (s *Server) setGroup(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	if !s.requireUnsealed(w) {
		return
	}
	var body struct {
		Name       string `json:"name"`
		AdminName  string `json:"admin_name"`
		AdminEmail string `json:"admin_email"`
	}
	json.NewDecoder(r.Body).Decode(&body)
	name := strings.TrimSpace(body.Name)
	if name == "" || len(name) > 60 {
		httpError(w, http.StatusBadRequest, "name must be 1–60 characters")
		return
	}
	// The administrator name + contact email are optional (empty clears them).
	adminName := strings.TrimSpace(body.AdminName)
	adminEmail := strings.TrimSpace(body.AdminEmail)
	if len(adminName) > 60 {
		httpError(w, http.StatusBadRequest, "administrator name must be at most 60 characters")
		return
	}
	// A light sanity check, not full RFC validation: a contact email should look
	// like one (an @ with something either side) and stay short.
	if adminEmail != "" && (len(adminEmail) > 120 || !isRoughEmail(adminEmail)) {
		httpError(w, http.StatusBadRequest, "contact email doesn't look valid")
		return
	}
	if err := s.db.setGroupName(name); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if err := s.db.setAdminName(adminName); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	if err := s.db.setAdminEmail(adminEmail); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "name": name, "admin_name": adminName, "admin_email": adminEmail})
}

// applySeededName seeds the space's name from LCHAT_GROUP_NAME — the create
// flow asks for the name up front now, and the provisioner delivers it via the
// instance env (control.go writes it at add-instance). Seed-only, never an
// override: a name the admin has since changed (or sealed) always wins, so
// restarts can't clobber it. The setup conversation composes with this — it
// offers "Keep "{name}"" when a name is already set rather than asking cold.
func applySeededName(db *DB) error {
	name := strings.TrimSpace(os.Getenv("LCHAT_GROUP_NAME"))
	if name == "" || db.groupNameSet() {
		return nil
	}
	// The create path caps at 60 too; belt-and-suspenders, at a rune boundary.
	if len(name) > 60 {
		cut := 60
		for cut > 0 && !utf8.RuneStart(name[cut]) {
			cut--
		}
		name = strings.TrimSpace(name[:cut])
	}
	if name == "" {
		return nil
	}
	return db.setGroupName(name)
}

// applySkipSetup is a TEST/DEV convenience (LCHAT_SKIP_SETUP=1): mark the
// first-run setup conversation complete and seed workable defaults, so a
// scratch instance is usable the moment its setup link is claimed — the
// claimer still becomes the admin, they just skip the conversation. Values an
// admin can change are seeded only when unset, so restarts never clobber
// in-test edits. Never set this on a real instance: it forfeits onboarding.
func applySkipSetup(db *DB) error {
	if strings.TrimSpace(os.Getenv("LCHAT_SKIP_SETUP")) == "" {
		return nil
	}
	log.Printf("LCHAT_SKIP_SETUP set: first-run setup conversation disabled (test/dev)")
	if err := db.setSetupComplete(true); err != nil {
		return err
	}
	// applySeededName already consumed LCHAT_GROUP_NAME; this only backfills the
	// dev default when nothing named the space at all.
	if !db.groupNameSet() {
		if err := db.setGroupName("Test Space"); err != nil {
			return err
		}
	}
	// Members can invite — the joiner flow is usually what a test instance is for.
	if _, ok, _ := db.getConfig("user_invites_enabled"); !ok {
		if err := db.setUsersCanInvite(true); err != nil {
			return err
		}
	}
	return nil
}

// trimAltText caps the photo's alt text at a RUNE boundary — a plain byte slice
// mid-emoji would store invalid UTF-8 and render as U+FFFD on the join card.
func trimAltText(s string) string {
	s = strings.TrimSpace(s)
	if len(s) <= 300 {
		return s
	}
	cut := 300
	for cut > 0 && !utf8.RuneStart(s[cut]) {
		cut--
	}
	return s[:cut]
}

// isRoughEmail is a deliberately loose check — just enough to reject obvious
// typos in the admin's optional contact address without pretending to validate
// deliverability. "a@b.c" passes; "not an email" doesn't.
func isRoughEmail(s string) bool {
	at := strings.IndexByte(s, '@')
	if at <= 0 || at == len(s)-1 {
		return false
	}
	return strings.Contains(s[at+1:], ".") && !strings.ContainsAny(s, " \t\n")
}

// ---- instance settings (admin) ------------------------------------------

// getSettings returns the instance settings the admin console manages.
func (s *Server) getSettings(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{
		"user_invites":          s.db.usersCanInvite(),
		"ai_enabled":            s.db.aiEnabled(),
		"bots_enabled":          s.db.botsEnabled(),
		"apps_enabled":          s.db.appsEnabled(),
		"member_apps_enabled":   s.db.memberAppsEnabled(),
		"space_installs_admins": s.db.spaceInstallsAdmins(),
		"admin_name":            s.db.getAdminName(),
		"admin_email":           s.db.getAdminEmail(),
		"description":           s.db.getGroupDescription(),
		"setup_complete":        s.db.setupComplete(),
		"update_auto":           s.db.updateAuto(),
		"update_download":       s.db.updateDownload(),
		"update_channel":        s.db.updateChannel(),
		"update_pin":            s.db.updatePin(),
		"update_major":          s.db.updateMajor(),
		"update":                s.updateInfo(),
	})
}

// setSettings toggles instance settings. Fields are pointers so an omitted field
// is left unchanged (a partial update).
func (s *Server) setSettings(w http.ResponseWriter, r *http.Request) {
	if !s.requireAdmin(w, r) {
		return
	}
	var body struct {
		UserInvites *bool `json:"user_invites"`
		// The feature gates (default on; see db.go): AI replies, bot creation,
		// apps, and members building their own apps. Enforcement lives at the
		// gated endpoints.
		AIEnabled         *bool `json:"ai_enabled"`
		BotsEnabled       *bool `json:"bots_enabled"`
		AppsEnabled       *bool `json:"apps_enabled"`
		MemberAppsEnabled *bool `json:"member_apps_enabled"`
		// Space-install policy: true = only admins may add apps for everyone.
		SpaceInstallsAdmins *bool `json:"space_installs_admins"`
		// The setup conversation marks itself done (or the admin dismisses it).
		SetupComplete *bool `json:"setup_complete"`
		// The photo's alt text, editable without re-uploading the image (the
		// admin panel's alt field). Plaintext branding, like the photo itself.
		AvatarAlt *string `json:"avatar_alt"`
		// Auto-update prefs (docs/server-releases.md); the box updater acts on
		// them, the instance just stores + reports them.
		UpdateAuto     *bool   `json:"update_auto"`
		UpdateDownload *bool   `json:"update_download"`
		UpdateChannel  *string `json:"update_channel"`
		// Pin to one exact version ("" clears): the updater skips a pinned
		// instance entirely. Set by `lchat update pin` / `deploy --pin`; cleared
		// from the admin UI by picking a channel.
		UpdatePin *string `json:"update_pin"`
		// Stay on one major version ("" clears): minors/patches follow the
		// channel, a major bump holds until the admin raises this.
		UpdateMajor *string `json:"update_major"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	// Validate everything before writing anything, so a rejected request never
	// half-applies (fields are independent config keys, not one transaction).
	if body.UpdateChannel != nil && !validChannel(*body.UpdateChannel) {
		httpError(w, http.StatusBadRequest, "unknown channel (edge, beta, or stable)")
		return
	}
	if body.UpdatePin != nil && *body.UpdatePin != "" && !validVersion(*body.UpdatePin) {
		httpError(w, http.StatusBadRequest, "invalid pin version")
		return
	}
	if body.UpdateMajor != nil && !validMajor(*body.UpdateMajor) {
		httpError(w, http.StatusBadRequest, "invalid major version (a number, or empty to follow everything)")
		return
	}
	if body.UserInvites != nil {
		was := s.db.usersCanInvite()
		if err := s.db.setUsersCanInvite(*body.UserInvites); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		// The invite pause is the moderation panic switch (issue #578) —
		// flips get a paper trail like every other moderation action.
		if was != *body.UserInvites {
			act := "invites.resumed"
			if !*body.UserInvites {
				act = "invites.paused"
			}
			s.db.addAudit(s.adminActor(r), act, "", "", "", "")
			// Every connected client baked USER_INVITES into its page at load
			// (index.html's meta tag) — without this, the toggle's effect on
			// the invite UI only ever showed up after a reload (issue #346).
			out, _ := json.Marshal(map[string]any{"type": "user_invites_changed", "enabled": *body.UserInvites})
			s.hub.broadcast <- outbound{data: out} // members:nil → everyone
		}
	}
	if body.AIEnabled != nil {
		// EXPLICIT consent is what signals, not the implicit default:
		// aiEnabled() reads true on a fresh space (absent key, the compat
		// default), so a plain was/now comparison would swallow the very
		// first "Bring Eleven in" — the feature's core case. Explicitly-on
		// before the write is the one state that stays silent.
		wasExplicitlyOn := s.db.aiEnabledExplicitly()
		if err := s.db.setAIEnabled(*body.AIEnabled); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
		// An explicit enable asks the provisioner to make sure this space's
		// sidecar exists (#858) — from ANY admin surface (setup flow, admin
		// console, Admin app), so the toggle and the provisioning can't
		// drift. Async and best-effort: idempotent end to end, no-op on
		// self-hosted instances (no meter env), and a lost signal is
		// re-sent by the next flip.
		if *body.AIEnabled && !wasExplicitlyOn {
			go s.signalAIOptIn()
		}
	}
	if body.BotsEnabled != nil {
		if err := s.db.setBotsEnabled(*body.BotsEnabled); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.AppsEnabled != nil {
		if err := s.db.setAppsEnabled(*body.AppsEnabled); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.MemberAppsEnabled != nil {
		if err := s.db.setMemberAppsEnabled(*body.MemberAppsEnabled); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.SpaceInstallsAdmins != nil {
		if err := s.db.setSpaceInstallsAdmins(*body.SpaceInstallsAdmins); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.SetupComplete != nil {
		if err := s.db.setSetupComplete(*body.SetupComplete); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.AvatarAlt != nil {
		// The one branding field in this settings grab-bag — while sealed it
		// must 409 like every other plaintext branding setter (alt text rides
		// inside the sealed blob instead).
		if !s.requireUnsealed(w) {
			return
		}
		if err := s.db.setConfig("server_avatar_alt", trimAltText(*body.AvatarAlt)); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.UpdateAuto != nil {
		if err := s.db.setUpdateAuto(*body.UpdateAuto); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.UpdateDownload != nil {
		if err := s.db.setUpdateDownload(*body.UpdateDownload); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.UpdateChannel != nil {
		if err := s.db.setUpdateChannel(*body.UpdateChannel); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.UpdatePin != nil {
		if err := s.db.setUpdatePin(*body.UpdatePin); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	if body.UpdateMajor != nil {
		if err := s.db.setUpdateMajor(*body.UpdateMajor); err != nil {
			httpError(w, http.StatusInternalServerError, "db error")
			return
		}
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "user_invites": s.db.usersCanInvite()})
}

// ---- helpers ------------------------------------------------------------

// noCache makes browsers revalidate static assets, so deploys take effect without
// a hard reload.
func noCache(h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Cache-Control", "no-cache")
		h.ServeHTTP(w, r)
	})
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(v)
}

func httpError(w http.ResponseWriter, status int, msg string) {
	writeJSON(w, status, map[string]any{"error": msg})
}

func boolStr(b bool) string {
	if b {
		return "1"
	}
	return "0"
}

func envOr(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

// envBytes reads a byte-count env var (a plain integer number of bytes), falling
// back to def when unset, unparseable, or non-positive.
func envBytes(key string, def int64) int64 {
	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
		if n, err := strconv.ParseInt(v, 10, 64); err == nil && n > 0 {
			return n
		}
	}
	return def
}

func printAdminLink(addr, token string) {
	host := addr
	if strings.HasPrefix(host, ":") {
		host = "localhost" + host
	}
	log.Printf("\n\n  Admin link (open once, keep it secret):\n  http://%s/admin#token=%s\n\n", host, token)
}

// ---- APNs (native iOS app) -----------------------------------------------

// apnsSubscribe registers an iPhone's APNs device token against the caller's
// session token, so the same suppression rules as Web Push apply. sandbox marks
// tokens from development builds (delivered via Apple's sandbox gateway).
func (s *Server) apnsSubscribe(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		APNsToken string `json:"apns_token"`
		Sandbox   bool   `json:"sandbox"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	if !apns.ValidDeviceToken(body.APNsToken) {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if err := s.db.addAPNsToken(APNsToken{APNsToken: body.APNsToken, Token: body.Token, Sandbox: body.Sandbox}); err != nil {
		httpError(w, http.StatusInternalServerError, "db error")
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "enabled": s.apns != nil})
}

func (s *Server) apnsUnsubscribe(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Token     string `json:"token"`
		APNsToken string `json:"apns_token"`
	}
	if json.NewDecoder(r.Body).Decode(&body) != nil {
		httpError(w, http.StatusBadRequest, "bad request")
		return
	}
	if !s.tokenOK(body.Token) {
		httpError(w, http.StatusForbidden, "not a member")
		return
	}
	_ = s.db.deleteAPNsToken(body.APNsToken)
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}