"""
Operator operations — one implementation, several front doors.

Three things ask this node to act: the CLI (over the loopback admin API), the
local admin UI, and — from Stage B3 — signed MNP messages from a paired client.
They must agree, and the way to make them agree is not to write the operation
three times and hope.

**C1 and C6 were both "a second path into the node with its own weaker
handshake."** Two implementations of `revoke` with two authorization checks is
the same shape one size down. So each operation lives here once, takes the
daemon's `state`, and knows nothing about HTTP, argv or MNP. The adapters
translate: `ui/app.py` turns `OpError` into a JSON response, the CLI prints it,
the MNP handler sends an error frame.

**Authorization is not here.** Reaching this module already means the caller got
past its adapter's check — the loopback session token (11.5.3) for the API, an
Ed25519 signature verified against the roster for MNP. These functions do what
they are told; deciding who may tell them is the adapter's job and stays visible
in the adapter.
"""

from __future__ import annotations

import asyncio
import logging
import re
from dataclasses import asdict
from pathlib import Path
from typing import Any

from meshbay_common.crypto import generate_gek, wrap_gek_aes
from meshbay_node.config import DEFAULT_CONFIG_PATH
from meshbay_common.join import ROLE_MEMBER, ROLE_OPERATOR
from meshbay_node.roots import RootError, RootSet

log = logging.getLogger(__name__)


class OpError(Exception):
    """
    An operation refused, with enough for any adapter to report it.

    `status` is an HTTP code because one adapter needs one; the others ignore it.
    `extra` carries the "here is what would have worked" payload — a bare "no
    such group" leaves an operator guessing at a UUID.
    """

    def __init__(self, message: str, *, status: int = 400,
                 extra: dict[str, Any] | None = None):
        super().__init__(message)
        self.message = message
        self.status = status
        self.extra = extra or {}

    def as_dict(self) -> dict:
        return {"error": self.message, **self.extra}


# ── Shared lookups ───────────────────────────────────────────────────────────

def _roster(state: dict):
    roster = state.get("roster")
    if not roster:
        raise OpError("Roster not available", status=503)
    return roster


def _hub(state: dict):
    hub = state.get("hub")
    if not hub or not hub._session:
        raise OpError("Hub not connected", status=503)
    return hub


def _group_ctx(state: dict, group_id: str) -> dict:
    groups_ctx = state.get("groups_ctx", {})
    if group_id not in groups_ctx:
        raise OpError("Group not hosted on this node", status=404,
                      extra={"available": [
                          {"id": gid} for gid in groups_ctx]})
    return groups_ctx[group_id]


def _config(state: dict):
    config = state.get("config")
    if not config:
        raise OpError("No config loaded", status=503)
    return config


# ── Roster ───────────────────────────────────────────────────────────────────

async def read_roster(state: dict, group_id: str = "") -> dict:
    roster = state.get("roster")
    if not roster:
        return {"identities": [], "members": [], "invites": []}
    members = await roster.list_members(group_id or None)
    members = [m for m in members if m.get("pk_ed25519") is not None]
    return {
        "identities": await roster.list_identities(),
        "members": members,
        "invites": await roster.list_invites(),
    }


async def resolve_user(state: dict, username: str) -> dict:
    """
    Map a username to an account id.

    The roster answers first — it is the node's own record. The hub is the
    fallback for identities pinned before invitations carried a name, and for
    people admitted through an open-join group. Only an account id comes back;
    no key is ever taken from there.
    """
    roster = state.get("roster")
    if roster:
        for ident in await roster.list_identities():
            if ident["username"] == username:
                return {"user_id": ident["user_id"], "source": "roster"}
    hub = state.get("hub")
    if hub and hub._session:
        try:
            account = await hub.get_user_pubkeys(username)
            return {"user_id": account["user_id"], "source": "hub"}
        except Exception:
            pass
    raise OpError(f"Unknown user {username!r}", status=404)


async def pair_operator(state: dict) -> dict:
    """
    Issue a one-time code that pairs a browser as this node's operator.

    The code is the whole point: it binds the operator's browser identity key to
    their account without asking the hub, which is what stops a hub from naming
    itself node administrator (M3, and the same substitution as H3). Returned
    once and stored only as a hash.
    """
    roster = _roster(state)
    user_id = state.get("node_user_id")
    if not user_id:
        raise OpError("Node not connected to hub yet", status=503)

    config = state.get("config")
    ttl = (config.node.pair_ttl_hours if config else 24) * 3600
    code = await roster.create_invite(
        group_id="",                 # operator authority is node-wide
        user_id=user_id,
        role=ROLE_OPERATOR,
        created_by="local-cli",
        ttl=ttl,
        username=(config.hub.username if config else ""),
    )
    invites = await roster.list_invites()
    expires = next((i["expires_at"] for i in invites
                    if i["user_id"] == user_id and i["role"] == ROLE_OPERATOR), "")
    return {"code": code, "expires_at": expires, "user_id": user_id}


async def create_invite(state: dict, group_id: str, username: str, *,
                        user_id: str = "",
                        created_by: str = "local-cli") -> dict:
    """
    Issue an invitation code.

    The hub is asked for the account id and nothing else — never for a key. A hub
    that answered with the wrong account would produce an invite whose code it
    never learns, since the code goes to a human out of band.

    When ``user_id`` is supplied directly (MNP path), the hub lookup is skipped.
    """
    roster = _roster(state)
    _group_ctx(state, group_id)
    if not user_id:
        hub = _hub(state)
        try:
            account = await hub.get_user_pubkeys(username)
        except Exception as e:
            raise OpError(f"Unknown user {username!r}: {e}", status=404) from e
        user_id = account["user_id"]

    config = state.get("config")
    ttl = (config.node.invite_ttl_hours if config else 168) * 3600
    code = await roster.create_invite(
        group_id=group_id,
        user_id=user_id,
        role=ROLE_MEMBER,
        created_by=created_by,
        ttl=ttl,
        username=username,
    )
    invites = await roster.list_invites()
    expires = next((i["expires_at"] for i in invites
                    if i["user_id"] == user_id
                    and i["group_id"] == group_id), "")
    return {"code": code, "expires_at": expires,
            "username": username, "user_id": user_id}


async def revoke_member(state: dict, user_id: str, group_id: str) -> dict:
    """
    Stop serving the group key to someone.

    Takes effect on their next connection: the key is wrapped on demand, so there
    is no stored bundle left behind that would outlive this. Rotating the group
    key is still required — they hold the current one.
    """
    roster = _roster(state)
    if not await roster.set_status(group_id, user_id, "revoked"):
        raise OpError("No such member in that group", status=404)
    log.info("Member revoked: user=%s group=%s", user_id[:8], group_id[:8])
    return {"status": "revoked", "user_id": user_id, "group_id": group_id,
            "reminder": "rotate the group key: meshbay-node gek rotate"}


async def unpin_member(state: dict, user_id: str) -> dict:
    """Forget a pinned identity, so the person can pair again with a new key."""
    roster = _roster(state)
    if not await roster.unpin(user_id):
        raise OpError("No such pinned identity", status=404)
    log.info("Identity unpinned: user=%s", user_id[:8])
    return {"status": "unpinned", "user_id": user_id}


# ── Group keys ───────────────────────────────────────────────────────────────

async def set_gek(state: dict, group_id: str, *, rotate: bool = False) -> dict:
    """
    Generate the group key and activate it, or rotate an existing one.

    Nothing is pre-wrapped for members. Each member's copy is produced when they
    connect, for a key they proved they hold (`join_request`) — pre-wrapping used
    to fetch public keys from the hub, which is H3 with the node as the victim
    instead of the inviter. Only the node's own copy is stored, so the daemon can
    reload the key across restarts without the operator's browser.

    **`rotate` generates a fresh key even when one exists.** That is the point of
    it: after a revocation the ex-member still holds the current key, and nothing
    else takes it away from them. Without `rotate` an existing key is kept, so
    running this twice is not destructive by accident.
    """
    ctx = _group_ctx(state, group_id)
    hub = _hub(state)

    if rotate and ctx.get("visibility") == "public":
        raise OpError(
            "Key rotation is not available for public groups", status=400)

    bundle_store = state.get("bundle_store")
    if not bundle_store:
        raise OpError("Bundle store not available", status=503)

    existing = ctx.get("gek")
    gek = generate_gek() if (rotate or not existing) else existing
    rotated = bool(existing) and gek is not existing
    errors: list[str] = []

    roster = state.get("roster")
    authorized = len(await roster.list_members(group_id)) if roster else 0

    node_user_id = hub._session.user_id if hub._session else None
    pk_x_node_raw = state.get("pk_x25519_raw")
    if pk_x_node_raw and node_user_id:
        try:
            node_bundle = wrap_gek_aes(gek, pk_x_node_raw)
            await bundle_store.store(
                group_id, f"_node_{node_user_id}",
                node_bundle["pk_eph_b64"], node_bundle["nonce_b64"],
                node_bundle["wrapped_b64"],
            )
            log.info("GEK wrapped for node keystore (daemon reload)")
        except Exception as e:
            errors.append(f"node keystore: {e}")
            log.warning("Failed to wrap GEK for node keystore: %s", e)

    ctx["gek"] = gek
    log.info("GEK %s for group %s — %d authorized member(s) will receive it "
             "on connect", "rotated" if rotated else "initialized",
             group_id[:8], authorized)

    # The transport holds its own view of the group; a rotation that did not
    # reach it would keep serving the old key until the daemon restarted.
    for transport_key in ("webrtc", "quic_server"):
        transport = state.get(transport_key)
        groups = getattr(transport, "_ctx", {}).get("groups") if transport else None
        if groups and group_id in groups:
            groups[group_id]["gek"] = gek

    indexes = state.get("indexes") or {}
    index = indexes.get(group_id)
    if index is not None:
        # The index is encrypted under the GEK; leaving the old key on it would
        # serve members a listing they cannot open.
        index.gek = gek

    return {
        "status": "rotated" if rotated else "ok",
        "group_id": group_id,
        "rotated": rotated,
        "authorized_members": authorized,
        "errors": errors,
    }


# ── Groups and roots ─────────────────────────────────────────────────────────

async def list_groups(state: dict) -> dict:
    """What this node hosts, with live status. Milestone 14.2."""
    config = state.get("config")
    groups_ctx = state.get("groups_ctx", {})
    peers = state.get("peers") or {}
    out = []
    for gid, ctx in groups_ctx.items():
        cfg = next((g for g in config.groups if g.id == gid), None) if config else None
        idx = ctx.get("index")
        roots = ctx.get("roots")
        out.append({
            "id": gid,
            "name": cfg.name if cfg else gid[:8],
            "visibility": cfg.visibility if cfg else "private",
            "join_policy": cfg.join_policy if cfg else "invite",
            "has_gek": bool(ctx.get("gek")),
            "file_count": idx.count if idx else 0,
            "index_version": idx.version if idx else 0,
            "roots": roots.describe() if roots else [],
            "peers": sum(1 for p in peers.values() if p.get("group_id") == gid),
        })
    roster = state.get("roster")
    has_operator = False
    if roster:
        members = await roster.list_members()
        has_operator = any(m["role"] == "operator" and m["status"] == "active"
                          for m in members)
    nd = config.node if config else None
    defaults = {
        "invite_ttl_hours": nd.invite_ttl_hours if nd else 168,
        "pair_ttl_hours": nd.pair_ttl_hours if nd else 24,
        "device_request_ttl_minutes": nd.device_request_ttl_minutes if nd else 60,
        "max_concurrent_streams": nd.max_concurrent_streams if nd else 8,
        "transcode_incompatible_video": nd.transcode_incompatible_video if nd else True,
    }
    if roster:
        settings = await roster.node_settings(defaults)
    else:
        settings = defaults
    return {"groups": out, "operator_paired": has_operator, "settings": settings}


async def attach_group(state: dict, name: str, shared_dir: str,
                       upload_dir: str = "") -> dict:
    """
    Write a new [[groups]] block into node.toml.

    The name-to-id lookup happens here because this process is the one logged
    into the hub. Nothing is created on the hub: the group already exists, this
    only tells the node to host it.
    """
    if not name or not shared_dir:
        raise OpError("name and shared_dir are required")
    config = _config(state)
    hub = _hub(state)
    try:
        mine = await hub.list_my_groups()
    except Exception as e:
        raise OpError(f"Could not list groups: {e}", status=502) from e

    match = [g for g in mine if g["id"] == name or g["name"] == name]
    if not match:
        raise OpError(f"No group of yours is called {name!r}", status=404,
                      extra={"available": [{"name": g["name"], "id": g["id"]}
                                           for g in mine]})
    if len(match) > 1:
        raise OpError(f"Several of your groups are called {name!r} — use the id",
                      status=409,
                      extra={"available": [{"name": g["name"], "id": g["id"]}
                                           for g in match]})
    group = match[0]

    if any(g.id == group["id"] for g in config.groups):
        raise OpError(f"{group['name']!r} is already hosted by this node", status=409)

    path = Path(shared_dir).expanduser()
    try:
        path.mkdir(parents=True, exist_ok=True)
    except OSError as e:
        raise OpError(f"Cannot create {path}: {e}") from e

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    # Appended as text rather than re-serialised: node.toml is hand-written and
    # full of comments explaining decisions, and a round trip through a TOML
    # writer would throw all of that away.
    join_policy = group.get("join_policy", "invite")
    block = (f'\n[[groups]]\n'
             f'id          = "{group["id"]}"\n'
             f'name        = "{group["name"]}"\n'
             f'visibility  = "{group.get("visibility", "private")}"\n'
             f'join_policy = "{join_policy}"\n')
    separate_upload = False
    if upload_dir:
        upload_path = Path(upload_dir).expanduser().resolve()
        if upload_path != path.resolve():
            separate_upload = True
            try:
                upload_path.mkdir(parents=True, exist_ok=True)
            except OSError as e:
                raise OpError(f"Cannot create {upload_path}: {e}") from e
            block += f'upload_dir  = "{upload_path}"\n'
    block += (f'\n  [[groups.roots]]\n'
              f'  path   = "{path}"\n')
    if not separate_upload:
        block += f'  upload = true\n'
    try:
        with conf_path.open("a") as f:
            f.write(block)
    except OSError as e:
        raise OpError(f"Cannot write {conf_path}: {e}", status=500) from e

    result = {"group_id": group["id"], "name": group["name"],
              "shared_dir": str(path), "config": str(conf_path),
              "note": "restart the node to pick it up"}
    if separate_upload:
        result["upload_dir"] = str(upload_path)
    return result


async def detach_group(state: dict, name: str) -> dict:
    """
    Remove a [[groups]] block from node.toml.

    Does not touch the hub — only stops this node from hosting the group
    after the next reload or restart.
    """
    if not name:
        raise OpError("group name or id is required")
    config = _config(state)

    match = [g for g in config.groups if g.id == name or g.name == name]
    if not match:
        raise OpError(f"No hosted group matches {name!r}", status=404,
                      extra={"available": [{"name": g.name, "id": g.id}
                                           for g in config.groups]})
    group = match[0]

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    text = conf_path.read_text()
    lines = text.split("\n")

    rng = _find_group_range(lines, group.id)
    if rng is None:
        raise OpError(f"Group {group.id[:8]} not found in {conf_path}")

    start, end = rng
    while end < len(lines) and lines[end].strip() == "":
        end += 1

    new_lines = lines[:start] + lines[end:]
    conf_path.write_text("\n".join(new_lines))
    log.info("Group detached: %s (%s) removed from %s", group.name, group.id[:8], conf_path)

    return {"group_id": group.id, "name": group.name, "config": str(conf_path),
            "note": "restart the node to stop hosting it"}


def _find_group_range(lines: list[str], group_id: str) -> tuple[int, int] | None:
    """Line range of a [[groups]] block by id: (start, end_exclusive)."""
    id_re = re.compile(r'^\s*id\s*=\s*"([^"]*)"')
    block_starts: list[int] = []
    for i, line in enumerate(lines):
        if line.strip() == "[[groups]]":
            block_starts.append(i)

    for j, start in enumerate(block_starts):
        boundary = block_starts[j + 1] if j + 1 < len(block_starts) else len(lines)
        for k in range(start + 1, boundary):
            s = lines[k].strip()
            if s.startswith("[") and s != "[[groups.roots]]":
                boundary = k
                break
        for k in range(start + 1, boundary):
            m = id_re.match(lines[k])
            if m and m.group(1) == group_id:
                return (start, boundary)
    return None


def _update_node_toml(conf_path: Path, updates: dict) -> None:
    """Write changed [node] settings back to node.toml without disturbing comments.

    For each key, if the line exists (commented or not) it is replaced in place;
    otherwise the key is appended to the end of the [node] section.
    """
    if not conf_path.exists():
        return
    text = conf_path.read_text()
    lines = text.split("\n")

    node_start = None
    node_end = len(lines)
    for i, line in enumerate(lines):
        stripped = line.strip()
        if stripped == "[node]":
            node_start = i
        elif node_start is not None and re.match(r'^\[', stripped):
            node_end = i
            break

    if node_start is None:
        lines.append("")
        lines.append("[node]")
        node_start = len(lines) - 1
        node_end = len(lines)

    remaining = dict(updates)
    for i in range(node_start + 1, node_end):
        for key in list(remaining):
            pattern = re.compile(
                r'^(\s*#?\s*)' + re.escape(key) + r'\s*=\s*.*$')
            if pattern.match(lines[i]):
                value = remaining.pop(key)
                if isinstance(value, bool):
                    lines[i] = f"{key} = {'true' if value else 'false'}"
                else:
                    lines[i] = f"{key} = {value}"
                break

    for key, value in remaining.items():
        if isinstance(value, bool):
            insert_line = f"{key} = {'true' if value else 'false'}"
        else:
            insert_line = f"{key} = {value}"
        lines.insert(node_end, insert_line)
        node_end += 1

    conf_path.write_text("\n".join(lines))


def _insert_roots_block(conf_path: Path, group_id: str,
                        root_block: str) -> None:
    """Append a [[groups.roots]] block inside the matching [[groups]] section."""
    text = conf_path.read_text()
    lines = text.split("\n")

    rng = _find_group_range(lines, group_id)
    if rng is None:
        raise OpError(f"Group {group_id[:8]} not found in {conf_path}")

    _start, end = rng
    insert_at = end
    while insert_at > _start + 1 and lines[insert_at - 1].strip() == "":
        insert_at -= 1

    new_lines = (lines[:insert_at]
                 + [""]
                 + root_block.rstrip("\n").split("\n")
                 + lines[insert_at:])
    conf_path.write_text("\n".join(new_lines))


def _remove_roots_block(conf_path: Path, group_id: str,
                        resolved_path: str) -> None:
    """Remove a [[groups.roots]] block whose resolved path matches."""
    text = conf_path.read_text()
    lines = text.split("\n")

    rng = _find_group_range(lines, group_id)
    if rng is None:
        raise OpError(f"Group {group_id[:8]} not found in {conf_path}")

    start, end = rng
    path_re = re.compile(r'^\s*path\s*=\s*"([^"]*)"')
    roots_starts: list[int] = []
    for i in range(start + 1, end):
        if lines[i].strip() == "[[groups.roots]]":
            roots_starts.append(i)

    for j, rs in enumerate(roots_starts):
        rs_end = roots_starts[j + 1] if j + 1 < len(roots_starts) else end
        for k in range(rs, rs_end):
            m = path_re.match(lines[k])
            if m:
                try:
                    p = str(Path(m.group(1)).expanduser().resolve())
                except OSError:
                    continue
                if p == resolved_path:
                    rm_start = rs
                    if rm_start > 0 and lines[rm_start - 1].strip() == "":
                        rm_start -= 1
                    new_lines = lines[:rm_start] + lines[rs_end:]
                    conf_path.write_text("\n".join(new_lines))
                    return

    raise OpError(f"Root path not found in config", status=404)


async def add_root(state: dict, group_id: str, path: str, *,
                   name: str = "", kind: str = "generic",
                   upload: bool = False) -> dict:
    """
    Add a directory to a group, refusing anything ambiguous.

    Validated against the group's existing roots *before* being written, so a
    config that would be refused at startup is refused here instead — where the
    operator is watching and can fix it.
    """
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    specs = [asdict(r) for r in cfg.roots]
    specs.append({"path": path, "name": name, "kind": kind, "upload": upload})
    try:
        built = RootSet.build(specs)
    except RootError as e:
        raise OpError(str(e)) from e

    added = built.roots[-1]

    try:
        added.path.mkdir(parents=True, exist_ok=True)
    except OSError as e:
        raise OpError(f"Cannot create {added.path}: {e}") from e

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    root_block = f'  [[groups.roots]]\n  path   = "{added.path}"'
    if name:
        root_block += f'\n  name   = "{added.name}"'
    if kind != "generic":
        root_block += f'\n  kind   = "{added.kind}"'
    if upload:
        root_block += f'\n  upload = true'
    _insert_roots_block(conf_path, group_id, root_block)

    from meshbay_node.config import RootSpec
    cfg.roots.append(RootSpec(
        path=str(added.path), name=added.name, kind=added.kind,
        upload=added.upload, direct=added.direct))

    log.info("Root added: %s → group %s", added.name, group_id[:8])
    return {"status": "added", "name": added.name, "path": str(added.path),
            "group_id": group_id, "roots": built.describe()}


async def remove_root(state: dict, group_id: str, root_name: str) -> dict:
    """Remove a named root from a group. At least one root must remain."""
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    from meshbay_common.paths import fold
    from meshbay_node.roots import derive_name
    target = fold(root_name)
    match_idx = None
    for i, r in enumerate(cfg.roots):
        try:
            rname = r.name or derive_name(Path(r.path).expanduser().resolve())
        except Exception:
            continue
        if fold(rname) == target:
            match_idx = i
            break

    if match_idx is None:
        raise OpError(f"No root named {root_name!r} in this group", status=404)
    if len(cfg.roots) < 2:
        raise OpError("Cannot remove the only root", status=400)

    removed = cfg.roots[match_idx]
    if removed.upload:
        raise OpError(
            "Cannot remove the upload root — file uploads and chat "
            "attachments are stored there", status=400)
    resolved = str(Path(removed.path).expanduser().resolve())

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    _remove_roots_block(conf_path, group_id, resolved)

    cfg.roots.pop(match_idx)
    remaining = [asdict(r) for r in cfg.roots]
    try:
        built = RootSet.build(remaining)
    except RootError:
        built = None

    log.info("Root removed: %s from group %s", root_name, group_id[:8])
    return {"status": "removed", "name": root_name, "group_id": group_id,
            "roots": built.describe() if built else []}


# ── Files ────────────────────────────────────────────────────────────────────

async def delete_file(state: dict, group_id: str, file_id: str) -> dict:
    """
    Remove a file from a group. Milestone 14.11 — the last operator action that
    needed a browser.

    Authorization happened in the adapter. On the loopback path that is the
    session token, which means physical or SSH access to the machine hosting the
    files — an operator who can run this can also `rm` the file, so the check is
    not weaker than the alternative.
    """
    ctx = _group_ctx(state, group_id)
    index = ctx.get("index")
    roots = ctx.get("roots")
    if not index or not roots:
        raise OpError("Group has no index", status=503)

    entry = index.get_entry(file_id)
    if not entry:
        raise OpError("No such file in this group", status=404)

    from meshbay_node.roots import entry_abs_path
    path = entry_abs_path(roots, entry)
    if path is None:
        raise OpError(
            f"{entry.name!r} is in root {entry.path.split('/')[0]!r}, which is "
            f"not readable right now — the file is frozen, not gone", status=409)

    try:
        path.unlink()
    except FileNotFoundError:
        # Already gone from disk; drop the stale entry rather than refusing.
        log.warning("Index named a file that is not on disk: %s", path)
    except OSError as e:
        raise OpError(f"Cannot delete {entry.name!r}: {e}", status=500) from e

    index.remove_entry(file_id)
    log.info("File deleted by operator: %s/%s", entry.path, entry.name)
    return {"status": "deleted", "name": entry.name, "path": entry.path,
            "group_id": group_id}


# ── Revocation denylist ──────────────────────────────────────────────────────

async def read_denylist(state: dict) -> dict:
    """Milestone 14.10 — what the node is currently refusing."""
    denylist = state.get("denylist")
    if not denylist:
        return {"users": [], "groups": [], "jtis": [], "count": 0}
    entries = denylist.entries()
    return {**entries, "count": sum(len(v) for v in entries.values())}


async def clear_denylist(state: dict, *, subject: str = "") -> dict:
    """
    Drop denylist entries — all of them, or one identifier.

    Deliberately not silent: a cleared denylist re-admits whoever it was keeping
    out, and the count is what tells the operator whether they undid one
    revocation or all of them.
    """
    denylist = state.get("denylist")
    if not denylist:
        raise OpError("No denylist in this process", status=503)
    removed = denylist.clear(subject)
    log.warning("Denylist cleared (%s): %d entr(y/ies) removed",
                subject or "all", removed)
    return {"status": "cleared", "removed": removed, "subject": subject or "all"}


# ── Upload policy ───────────────────────────────────────────────────────────

async def set_member_upload(state: dict, group_id: str, allowed: bool) -> dict:
    """
    Turn uploading by ordinary members on or off.

    The setting lives on the node (roster.db), not on the hub and not in
    node.toml — changing it must not rewrite the operator's config file,
    and must not need a restart.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_member_upload(group_id, allowed,
                                   set_by=state.get("node_user_id", ""))
    ctx["member_upload"] = allowed
    log.info("Upload policy: %s for group %s", "on" if allowed else "off",
             group_id[:8])
    return {"allowed": allowed, "group_id": group_id}


# ── Node settings ────────────────────────────────────────────────────────────

async def set_node_settings(state: dict, settings: dict) -> dict:
    """Update node-level daemon settings. Writes to both roster.db and node.toml."""
    roster = _roster(state)
    config = _config(state)
    nd = config.node
    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)

    allowed_keys = {
        "invite_ttl_hours": ("int", roster.SETTING_INVITE_TTL),
        "pair_ttl_hours": ("int", roster.SETTING_PAIR_TTL),
        "device_request_ttl_minutes": ("int", roster.SETTING_DEVICE_TTL),
        "max_concurrent_streams": ("int", roster.SETTING_MAX_STREAMS),
        "transcode_incompatible_video": ("bool", roster.SETTING_TRANSCODE),
    }

    set_by = state.get("node_user_id", "")
    updated = {}
    for key, value in settings.items():
        if key not in allowed_keys:
            continue
        kind, setting_key = allowed_keys[key]
        if kind == "int":
            try:
                v = int(value)
            except (TypeError, ValueError):
                raise OpError(f"{key} must be an integer")
            if v < 1:
                raise OpError(f"{key} must be positive")
            setattr(nd, key, v)
            await roster.set_node_setting(setting_key, str(v), set_by)
            updated[key] = v
        elif kind == "bool":
            v = bool(value)
            setattr(nd, key, v)
            await roster.set_node_setting(setting_key, "1" if v else "0", set_by)
            updated[key] = v

    if updated:
        _update_node_toml(conf_path, updated)
        if "max_concurrent_streams" in updated:
            webrtc = state.get("webrtc")
            if webrtc and hasattr(webrtc, '_stream_sem'):
                webrtc._stream_sem = asyncio.Semaphore(updated["max_concurrent_streams"])

    log.info("Node settings updated: %s", updated)
    return {"updated": updated}


# ── Applications ─────────────────────────────────────────────────────────────

async def set_enabled_apps(state: dict, group_id: str, apps: list[str]) -> dict:
    """
    Which group "applications" (Chat, Files, ...) are shown to members.

    Same shape as `set_member_upload`: lives on the node (roster.db), takes
    effect without a restart, and is signed by the operator (webrtc_server.py
    checks the caller's own admin-authority allow-list before this runs).
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_enabled_apps(group_id, apps,
                                  set_by=state.get("node_user_id", ""))
    ctx["enabled_apps"] = apps
    log.info("Enabled apps for group %s: %s", group_id[:8], ",".join(sorted(apps)))
    return {"apps": apps, "group_id": group_id}


# ── TMDB config (Videos app) ─────────────────────────────────────────────────

async def set_tmdb_config(state: dict, token: str | None = None,
                          language: str | None = None) -> dict:
    """
    Whether the node uses a custom API token instead of the shipped default,
    and in what language it queries TMDB (docs/mediacenter.md §5.5).

    Node-wide (roster.py group_settings, group_id="") rather than per-group
    like set_member_upload/set_enabled_apps: the token and the shared-cache
    language are one operator's budget and one credential, not a per-group
    or per-viewer concern. Whether TMDB is used *at all* is the per-group
    decision set_tmdb_enabled below makes instead. `token=""` explicitly
    clears a previously-set custom token (reverts to the shipped default);
    `token=None` leaves whatever was there unchanged. Same discipline for
    `language`.
    """
    roster = _roster(state)
    await roster.set_tmdb_config(token, language, set_by=state.get("node_user_id", ""))
    # `token=None` means "leave whatever was there" (§ set_tmdb_config's own
    # docstring) — so the customized flag only changes when a value (a real
    # token, or "" to clear one) was actually given.
    if token is not None:
        state["tmdb_token_customized"] = bool(token)
    if language is not None:
        state["tmdb_language"] = language
    log.info("TMDB config: custom_token=%s language=%s",
             bool(token), language or state.get("tmdb_language", ""))
    return {
        "token_customized": state.get("tmdb_token_customized", False),
        "language": state.get("tmdb_language", ""),
    }


async def set_tmdb_enabled(state: dict, group_id: str, enabled: bool) -> dict:
    """
    Whether TMDB lookups run for this group at all (docs/mediacenter.md
    §5.5) — per-group, unlike set_tmdb_config above: an operator running a
    real media library alongside test/demo groups on one node wants
    outbound TMDB traffic (and API quota) spent for the one that needs it,
    not all of them just because one process serves both.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_tmdb_enabled(group_id, enabled, set_by=state.get("node_user_id", ""))
    ctx["tmdb_enabled"] = enabled
    log.info("TMDB enabled for group %s: %s", group_id[:8], enabled)
    return {"enabled": enabled, "group_id": group_id}


# ── MusicBrainz config (Music app) ───────────────────────────────────────────

# set_musicbrainz_config removed — MusicBrainz contact is now the owner's
# hub email, resolved at login (daemon.py / musicbrainz.py).

async def set_musicbrainz_enabled(state: dict, group_id: str, enabled: bool) -> dict:
    """
    Whether MusicBrainz lookups run for this group at all
    (docs/musicbay.md §6) — per-group from the start, same reasoning as
    set_tmdb_enabled: a real media-library group and a test/demo group on
    one node need not share the decision to make outbound requests.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_musicbrainz_enabled(group_id, enabled, set_by=state.get("node_user_id", ""))
    ctx["musicbrainz_enabled"] = enabled
    log.info("MusicBrainz enabled for group %s: %s", group_id[:8], enabled)
    return {"enabled": enabled, "group_id": group_id}


async def set_video_root(state: dict, group_id: str, path: str) -> dict:
    """
    Which folder (possibly a subfolder of a shared root) is the Videos app's
    entry point for this group. Same shape as set_enabled_apps: lives on the
    node (roster.db), takes effect without a restart, signed by the operator.
    `path=""` clears it — the Videos tab then asks for one to be chosen
    before anything (including TMDB enrichment, docs/mediacenter.md §5.2)
    runs, rather than defaulting to the whole shared index.

    A non-empty path fires (never awaits) a sweep of whatever that folder
    already contains: the ordinary per-change enrichment path only ever
    looks at files new since the last broadcast, so anything already sitting
    in a folder before it became the video_root would otherwise never be
    picked up.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_video_root(group_id, path, set_by=state.get("node_user_id", ""))
    ctx["video_root"] = path
    log.info("Videos root for group %s: %r", group_id[:8], path)
    if path:
        enrich_fn = state.get("enrich_video_root_fn")
        if enrich_fn:
            asyncio.ensure_future(enrich_fn(group_id))
    return {"path": path, "group_id": group_id}


async def set_audio_root(state: dict, group_id: str, path: str) -> dict:
    """
    Same shape as set_video_root above — the Music app's own entry point,
    added later (docs/musicbay.md's original "no root, works over the
    whole shared tree" simplification didn't hold up against a real messy
    library). `path=""` clears it — the Music tab then asks for one to be
    chosen before anything (including tag/cover enrichment) runs, rather
    than defaulting to the whole shared index.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_audio_root(group_id, path, set_by=state.get("node_user_id", ""))
    ctx["audio_root"] = path
    log.info("Music root for group %s: %r", group_id[:8], path)
    if path:
        enrich_fn = state.get("enrich_audio_root_fn")
        if enrich_fn:
            asyncio.ensure_future(enrich_fn(group_id))
    return {"path": path, "group_id": group_id}


async def set_photo_roots(state: dict, group_id: str, roots: list[str]) -> dict:
    """
    Which folder(s) are the Photos app's entry points for this group. Unlike
    `set_video_root`/`set_audio_root`, the whole *set* is replaced in one
    call (docs/photos.md §2.1) — signed once, same shape as
    `set_enabled_apps`, rather than one op per root added/removed.

    Always fires a sweep, even to an empty list: a root just added needs its
    existing contents enriched (nothing else re-visits already-indexed
    entries), and a root just removed leaves its cache entries harmlessly
    unused rather than needing any cleanup — re-sweeping the new set costs
    nothing when it's empty.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_photo_roots(group_id, roots, set_by=state.get("node_user_id", ""))
    ctx["photo_roots"] = roots
    log.info("Photo roots for group %s: %s", group_id[:8], ", ".join(sorted(roots)) or "(none)")
    enrich_fn = state.get("enrich_photo_roots_fn")
    if enrich_fn:
        asyncio.ensure_future(enrich_fn(group_id))
    return {"roots": roots, "group_id": group_id}


# ── Scan settings ────────────────────────────────────────────────────────────

async def set_scan_settings(state: dict, group_id: str, reconcile_interval_secs: float,
                            debounce_secs: float) -> dict:
    """
    How often the indexer's reconciliation backstop runs, and how long a
    changed file is left alone before being hashed (indexer.py
    DirectoryIndexer). Persisted like set_member_upload/set_enabled_apps —
    but there is also a *live* DirectoryIndexer object to update, since it
    reads these once at construction and runs its own background loop with
    them rather than consulting groups_ctx on every use.
    """
    roster = _roster(state)
    await roster.set_scan_settings(group_id, reconcile_interval_secs, debounce_secs,
                                   set_by=state.get("node_user_id", ""))
    indexer = state.get("indexers", {}).get(group_id)
    if indexer:
        indexer.reconcile_secs = reconcile_interval_secs
        indexer.debounce_secs = debounce_secs
        # Apply the new interval now rather than after whatever backoff had
        # already stretched the wait to.
        indexer.note_activity()
    # Optional, unlike _group_ctx(): a group can be persisted here before it
    # is hot-loaded (or in a test that only cares about the roster/indexer
    # side), and that must not turn a successful write into a 404.
    ctx = state.get("groups_ctx", {}).get(group_id)
    if ctx is not None:
        ctx["reconcile_interval_secs"] = reconcile_interval_secs
        ctx["debounce_secs"] = debounce_secs
    log.info("Scan settings for group %s: reconcile=%.0fs debounce=%.0fs",
             group_id[:8], reconcile_interval_secs, debounce_secs)
    return {"reconcile_interval_secs": reconcile_interval_secs,
            "debounce_secs": debounce_secs, "group_id": group_id}


# ── Index cache maintenance ───────────────────────────────────────────────────
#
# The (path, size, mtime) -> hash accelerator (indexer/cache.py) is node-wide
# and grows for as long as a path was ever seen — a folder an operator later
# stops sharing (root removed, or every group hosting it is deleted) leaves
# its rows behind forever otherwise. Nothing about correctness needs this:
# a stale row just sits unused (lookup() keys on the live path string, so a
# path nothing scans any more is never looked up). This is disk space
# hygiene the operator can run when they want it, not a background job.

async def index_cache_stats(state: dict) -> dict:
    """Row count only — cheap, safe to call on every dashboard render.
    The actual staleness check (prune_index_cache) is not this cheap and
    must never run implicitly."""
    cache = state.get("index_cache")
    return {"count": await cache.count() if cache else 0}


async def prune_index_cache(state: dict) -> dict:
    """
    Drop cache rows that cannot be right for anything any more: the path is
    not under any group's root at all, or it is under a root that is
    available right now and the file is genuinely gone from disk.

    Deliberately leaves alone anything under a root that is currently
    *unavailable* (a disconnected drive) — indexer.py's own rule is that
    such a root freezes rather than empties, precisely so it does not pay a
    full rehash the moment it comes back. Pruning through an unavailable
    root here would reintroduce exactly that cost via a different door, so
    an owning-but-unavailable root wins over "the file isn't there right
    now" every time, unconditionally.

    A row lost here costs one rehash the next time that path is scanned,
    never a wrong answer: lookup() (cache.py) always re-validates size and
    mtime against a live stat() before trusting a cached hash.
    """
    cache = state.get("index_cache")
    if cache is None:
        raise OpError("No index cache in this process", status=503)

    indexers = list((state.get("indexers") or {}).values())
    roots = [root for indexer in indexers for root in indexer.roots]

    def _is_stale(path_str: str) -> bool:
        path = Path(path_str)
        owning = [r for r in roots if r.path in path.parents]
        if not owning:
            return True
        if any(not r.available for r in owning):
            return False
        return not path.exists()

    paths = await cache.all_paths()
    stale = await asyncio.to_thread(lambda: [p for p in paths if _is_stale(p)])
    await cache.remove_many(stale)
    log.info("Index cache pruned: %d stale row(s) removed, %d kept",
             len(stale), len(paths) - len(stale))
    return {"status": "pruned", "removed": len(stale), "kept": len(paths) - len(stale)}


# ── Videos: force TMDB re-matching ───────────────────────────────────────────
#
# `media_cache.file_tmdb` is keyed by a file's content hash and is otherwise
# only pruned on deletion, so a fixed matcher/parser never dislodges a match
# already in cache. This drops a group's *auto-resolved* mappings so the
# next `media_meta_req` for each poster tile re-resolves against the current
# code. Re-resolution is lazy and calls TMDB once per unique title — real
# API budget — so this is an explicit operator action, never a background job.
# Manual "Fix match" corrections (media_cache.tmdb_override) are kept.

async def rematch_video(state: dict, group_id: str) -> dict:
    media_cache = state.get("media_cache")
    if media_cache is None:
        raise OpError("No media cache in this process", status=503)
    indexer = (state.get("indexers") or {}).get(group_id)
    if indexer is None:
        raise OpError("Unknown group", status=404)
    file_ids = [e.id for e in indexer.index.entries if e.type == "video"]
    removed = await media_cache.clear_tmdb_matches(file_ids)
    log.info("Video rematch for group %s: %d auto match(es) cleared across %d video file(s)",
             group_id[:8], removed, len(file_ids))
    return {"status": "cleared", "removed": removed, "videos": len(file_ids),
            "group_id": group_id}


# ── Reload ──────────────────────────────────────────────────────────────────

async def reload_config(state: dict) -> dict:
    """Hot-reload node.toml without dropping connections. Blocks until the
    reload actually finishes — see start_reload for why the loopback route
    uses that instead."""
    reload_fn = state.get("reload_fn")
    if not reload_fn:
        raise OpError("Reload not available", status=503)
    await reload_fn()
    return {"status": "reloaded"}


async def start_reload(state: dict) -> dict:
    """
    Same as reload_config, but does not wait for the reload to finish.

    The loopback route uses this one: the Electron bridge caps every call at
    a fixed 30s (main.js node:call), and hot-loading a brand-new group runs
    its full initial scan synchronously inside _reload_config_inner()
    (daemon.py) before that coroutine returns — minutes, not seconds, on a
    real library (found against a 45 GB group on the same slow disk the
    StarWars benchmark used). The reload keeps running on the daemon's own
    event loop either way; add_root/remove_root below already fire it the
    same way for exactly this reason.
    """
    reload_fn = state.get("reload_fn")
    if not reload_fn:
        raise OpError("Reload not available", status=503)
    asyncio.ensure_future(reload_fn())
    return {"status": "reloading"}