path: root/packages/meshbay-node/src/meshbay_node/ops.py

"""
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),
        })
    return {"groups": out}


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 _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}


# ── 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, enabled: bool, token: str | None = None,
                          language: str | None = None) -> dict:
    """
    Whether the node calls TMDB at all, whether it 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: TMDB is one operator's budget,
    one credential and one shared cache, not a per-group or per-viewer
    concern. `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(enabled, token, language, set_by=state.get("node_user_id", ""))
    state["tmdb_enabled"] = enabled
    # `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: enabled=%s custom_token=%s language=%s",
             enabled, bool(token), language or state.get("tmdb_language", ""))
    return {
        "enabled": enabled,
        "token_customized": state.get("tmdb_token_customized", False),
        "language": state.get("tmdb_language", ""),
    }


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}


# ── 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}


# ── 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"}