"""Typed contracts for autonomous cross-gateway hosted-room members.

The Desktop may bootstrap an invitation but is never the issuer or runtime
courier: the target gateway verifies a scoped grant and the full task
coordinates before admitting any model or tool work.
"""

from __future__ import annotations

import base64
import hashlib
import hmac
import ipaddress
import json
import math
import os
import re
import stat
import time
import urllib.parse
from dataclasses import asdict, dataclass
from functools import lru_cache, partial
from pathlib import Path
from typing import Any, Callable, Iterable, Literal, Mapping

from gateway.hosted_room_execution_policy import RoomExecutionPolicy, execution_policy_mapping
from gateway.hosted_rooms_common import exact_fields, identifier, positive_int


# v2 adds authority/member lineage to scoped grants and is deliberately not
# wire-compatible with the unpublished v1 draft; mixed gateways must fall back
# to Desktop-driven rooms instead of accepting a weaker token shape.
PROTOCOL_VERSION = 2
MAX_TOKEN_BYTES = 16 * 1024
MAX_PROMPT_BYTES = 256 * 1024
_IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$")
_DIGEST_RE = re.compile(r"^[0-9a-f]{64}$")
_LINK_MODES = frozenset({"direct", "overlay", "relay", "pull", "desktop"})
LinkMode = Literal["direct", "overlay", "relay", "pull", "desktop"]
TransportSecurity = Literal["tls", "loopback"]


class HostedRoomPeerError(ValueError):
    """Base error for malformed or unauthorized peer-room input."""


class HostedRoomGrantError(HostedRoomPeerError):
    """Raised when a room-scoped grant is invalid or expired."""


_ROOM_GRANT_SECRET_FILE = ".room-link-grant-secret"


def _fsync_dir(directory: Path) -> None:
    try:
        parent_fd = os.open(directory, os.O_RDONLY)
        try:
            os.fsync(parent_fd)
        finally:
            os.close(parent_fd)
    except OSError:
        pass


@lru_cache(maxsize=32)
def _gateway_room_grant_secret_for_home(home_value: str) -> bytes:
    """Load one restart-scoped grant secret for an exact installation root."""
    home = Path(home_value)
    home.mkdir(parents=True, exist_ok=True)
    path = home / _ROOM_GRANT_SECRET_FILE

    def _read() -> bytes:
        data = path.read_bytes()
        if len(data) != 32:
            raise HostedRoomGrantError("gateway RoomLink secret is invalid")
        if stat.S_IMODE(path.stat().st_mode) & 0o077:
            path.chmod(0o600)
        return data

    try:
        material = _read()
    except FileNotFoundError:
        # Atomic create: O_EXCL temp file, hard-link into place (loser re-reads
        # the winner's secret), fsync the directory, always drop the temp name.
        material = os.urandom(32)
        temporary = home / f".{_ROOM_GRANT_SECRET_FILE}.{os.getpid()}.{os.urandom(8).hex()}"
        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
        try:
            with os.fdopen(fd, "wb", closefd=True) as stream:
                stream.write(material)
                stream.flush()
                os.fsync(stream.fileno())
            try:
                os.link(temporary, path)
            except FileExistsError:
                material = _read()
            else:
                _fsync_dir(home)
        finally:
            temporary.unlink(missing_ok=True)
    return hmac.new(material, b"hermes-hosted-room-installation-grant-v1", hashlib.sha256).digest()


def gateway_room_grant_secret(root: Path | str | None = None) -> bytes:
    """Load or atomically mint the gateway-only RoomLink signing secret.

    API keys are bearer credentials known to clients and may be profile scoped;
    they must never become grant-signing authority. This secret lives in the
    installation root, is not exposed by configuration or capability RPCs, and
    is shared only by the gateway processes that serve this installation.
    """
    if root is None:
        from hermes_constants import get_hermes_home

        # Profile routing uses a context-local HERMES_HOME override. The process
        # environment retains the installation root and is the authority here.
        root = os.environ.get("HERMES_HOME") or get_hermes_home()
    return _gateway_room_grant_secret_for_home(str(Path(root).expanduser().resolve()))


def derive_room_grant_secret(api_key: str) -> bytes:
    """Domain-separate room grants from the configured API key.

    The API-server startup guard enforces the production key-strength policy;
    this helper keeps a lower structural floor for isolated contract tests.
    """
    if not isinstance(api_key, str) or len(api_key) < 8:
        raise HostedRoomGrantError("room grants require a strong gateway API key")
    return hmac.new(api_key.encode("utf-8"), b"hermes-hosted-room-grant-v1", hashlib.sha256).digest()


def _identifier(value: Any, *, field: str) -> str:
    return identifier(
        value, label=field, error=HostedRoomPeerError, max_chars=256, pattern=_IDENTIFIER_RE,
        invalid=f"{field} is invalid",
    )


def _positive_int(value: Any, *, field: str) -> int:
    return positive_int(value, error=HostedRoomPeerError, message=f"{field} must be a positive integer")


def _digest(value: Any, *, field: str) -> str:
    if not isinstance(value, str) or not _DIGEST_RE.fullmatch(value):
        raise HostedRoomPeerError(f"{field} must be a sha256 digest")
    return value


_exact_fields = partial(
    exact_fields, error=HostedRoomPeerError, missing_fmt="{label} missing fields: {fields}",
    unknown_fmt="{label} unknown fields: {fields}",
)


def _canonical_json(value: Mapping[str, Any]) -> bytes:
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("ascii")


def _b64encode(value: bytes) -> str:
    return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")


def _b64decode(value: str) -> bytes:
    try:
        return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
    except Exception as exc:
        raise HostedRoomGrantError("room grant encoding is invalid") from exc


def _split_token(token: str) -> tuple[str, str]:
    encoded_token, separator, signature_token = token.partition(".")
    if not separator:
        raise HostedRoomGrantError("room grant is invalid")
    return encoded_token, signature_token


def _parse_link_modes(links_raw: Any) -> tuple[LinkMode, ...]:
    if not isinstance(links_raw, list) or not links_raw:
        raise HostedRoomPeerError("link_modes must be a non-empty list")
    if any(item not in _LINK_MODES for item in links_raw):
        raise HostedRoomPeerError("link_modes contains an unsupported mode")
    return tuple(dict.fromkeys(links_raw))


def _parse_endpoint(endpoint: Any) -> tuple[str | None, str | None, TransportSecurity | None]:
    """Return ``(url, reason, transport_security)`` for an advertised endpoint capability."""
    if not isinstance(endpoint, Mapping) or not isinstance(endpoint.get("available"), bool):
        raise HostedRoomPeerError("endpoint capability is invalid")
    if not endpoint["available"]:
        _exact_fields(endpoint, required={"available", "reason"}, label="endpoint capability")
        return None, _identifier(endpoint["reason"], field="endpoint.reason"), None
    _exact_fields(endpoint, required={"available", "url", "transport_security"}, label="endpoint capability")
    url, transport_security = validate_room_link_url(endpoint["url"])
    if endpoint["transport_security"] != transport_security:
        raise HostedRoomPeerError("endpoint transport_security does not match its URL")
    return url, None, transport_security


_CATALOG_FIELDS = {
    "installation_id", "protocol_versions", "link_modes", "persistent_process", "text",
    "attachments", "execution_policy", "catalog_digest",
}


@dataclass(frozen=True)
class GatewayRoomCatalog:
    """Authenticated gateway capabilities inherited by its Bots."""

    installation_id: str
    protocol_versions: tuple[int, ...]
    link_modes: tuple[LinkMode, ...]
    persistent_process: bool
    text: bool
    attachments: bool
    execution_policy: RoomExecutionPolicy
    catalog_digest: str
    endpoint_url: str | None = None
    endpoint_reason: str | None = None
    transport_security: TransportSecurity | None = None

    @classmethod
    def from_mapping(cls, value: Mapping[str, Any]) -> "GatewayRoomCatalog":
        _exact_fields(value, required=_CATALOG_FIELDS, optional={"endpoint"}, label="capability catalog")
        installation_id = _identifier(value["installation_id"], field="installation_id")
        versions_raw = value["protocol_versions"]
        if not isinstance(versions_raw, list) or not versions_raw:
            raise HostedRoomPeerError("protocol_versions must be a non-empty list")
        versions = tuple(sorted({_positive_int(item, field="protocol_version") for item in versions_raw}))
        links = _parse_link_modes(value["link_modes"])
        for field in ("persistent_process", "text", "attachments"):
            if not isinstance(value[field], bool):
                raise HostedRoomPeerError(f"{field} must be a boolean")
        policy = RoomExecutionPolicy.from_mapping(value["execution_policy"])
        endpoint_url = endpoint_reason = transport_security = None
        if "endpoint" in value:
            endpoint_url, endpoint_reason, transport_security = _parse_endpoint(value["endpoint"])
        catalog = cls(
            installation_id=installation_id, protocol_versions=versions, link_modes=links,
            persistent_process=value["persistent_process"], text=value["text"],
            attachments=value["attachments"], execution_policy=policy,
            catalog_digest=_digest(value["catalog_digest"], field="catalog_digest"),
            endpoint_url=endpoint_url, endpoint_reason=endpoint_reason,
            transport_security=transport_security,
        )
        unsigned = catalog.as_mapping()
        del unsigned["catalog_digest"]
        expected = hashlib.sha256(_canonical_json(unsigned)).hexdigest()
        if not hmac.compare_digest(expected, catalog.catalog_digest):
            raise HostedRoomPeerError("catalog_digest does not match the catalog")
        return catalog

    def as_mapping(self) -> dict[str, Any]:
        """Canonical catalog mapping; ``endpoint`` appears only when advertised."""
        value = {
            "installation_id": self.installation_id, "protocol_versions": list(self.protocol_versions),
            "link_modes": list(self.link_modes), "persistent_process": self.persistent_process,
            "text": self.text, "attachments": self.attachments,
            "execution_policy": self.execution_policy.as_mapping(), "catalog_digest": self.catalog_digest,
        }
        if self.endpoint_url is not None or self.endpoint_reason is not None:
            value["endpoint"] = self.endpoint_mapping()
        return value

    def endpoint_mapping(self) -> dict[str, Any]:
        """Return the normalized self-advertised endpoint capability."""
        if self.endpoint_url is not None:
            return {
                "available": True, "url": self.endpoint_url, "transport_security": self.transport_security,
            }
        return {"available": False, "reason": self.endpoint_reason or "not_configured"}


def catalog_mapping(
    *, installation_id: str, protocol_versions: Iterable[int] = (PROTOCOL_VERSION,),
    link_modes: Iterable[LinkMode] = ("direct", "pull"), persistent_process: bool, text: bool = True,
    attachments: bool = False, endpoint: Mapping[str, Any] | None = None, target_profile: str | None = None,
    execution_policy: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a canonical catalog mapping with its digest."""
    # A Desktop-managed gateway exits with the app: the caller's flag is only an
    # upper bound, so call sites that still pass ``True`` stay honest.
    persistent_process = bool(persistent_process and os.getenv("HERMES_DESKTOP") != "1")
    profile = (
        str(target_profile or "").strip() or (os.getenv("HERMES_PROFILE") or "default").strip() or "default"
    )
    checked_policy = RoomExecutionPolicy.from_mapping(
        execution_policy or execution_policy_mapping(target_profile=profile)
    )
    # A RoomLink run is initiated by another installation. Process-wide YOLO
    # mode bypasses the scoped approval ContextVar, so rewriting the advertised
    # policy cannot make it safe: refuse until manual or smart approvals are on.
    if checked_policy.approval_mode == "off":
        raise HostedRoomPeerError("remote room execution requires manual or smart approvals")
    value = {
        "installation_id": _identifier(installation_id, field="installation_id"),
        "protocol_versions": sorted(
            {_positive_int(item, field="protocol_version") for item in protocol_versions}
        ),
        # Direct HTTPS/loopback is the only RoomLink transport implemented by
        # this backend slice. Do not advertise pull/relay placeholders.
        "link_modes": [mode for mode in dict.fromkeys(link_modes) if mode == "direct"],
        "persistent_process": persistent_process, "text": bool(text), "attachments": bool(attachments),
        "execution_policy": checked_policy.as_mapping(),
        "endpoint": dict(local_room_link_endpoint() if endpoint is None else endpoint),
    }
    value["catalog_digest"] = hashlib.sha256(_canonical_json(value)).hexdigest()
    GatewayRoomCatalog.from_mapping(value)
    return value


def local_catalog_mapping(
    *, installation_id: str, protocol_versions: Iterable[int] = (PROTOCOL_VERSION,),
    link_modes: Iterable[LinkMode] = ("direct", "pull"), text: bool = True, attachments: bool = False,
    target_profile: str | None = None, execution_policy: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
    """Build the one truthful catalog advertised by this local process."""
    return catalog_mapping(
        installation_id=installation_id, protocol_versions=protocol_versions, link_modes=link_modes,
        persistent_process=True, text=text, attachments=attachments, target_profile=target_profile,
        execution_policy=execution_policy,
    )


def local_room_link_endpoint(value: Any | None = None) -> dict[str, Any]:
    """Return the validated endpoint this gateway explicitly advertises."""
    configured = _configured_room_link_url() if value is None else value
    if not str(configured or "").strip():
        return {"available": False, "reason": "not_configured"}
    try:
        url, transport_security = validate_room_link_url(configured)
    except HostedRoomPeerError:
        return {"available": False, "reason": "invalid_configuration"}
    return {"available": True, "url": url, "transport_security": transport_security}


@lru_cache(maxsize=16)
def _room_link_url_from_config(home: str) -> str | None:
    """Read the restart-scoped user setting without polling config on probes."""
    from gateway.config import load_gateway_config
    from hermes_constants import get_hermes_home, reset_hermes_home_override, set_hermes_home_override

    if str(get_hermes_home()) == home:
        value = load_gateway_config().room_link_url
    else:
        token = set_hermes_home_override(home)
        try:
            value = load_gateway_config().room_link_url
        finally:
            reset_hermes_home_override(token)
    return value.strip() if isinstance(value, str) and value.strip() else None


def _configured_room_link_url() -> str | None:
    """Resolve the explicit endpoint: env override > profile config > root config."""
    override = os.getenv("HERMES_ROOM_LINK_URL")
    if override is not None:
        return override
    from hermes_constants import get_default_hermes_root, get_hermes_home

    home = get_hermes_home()
    configured = _room_link_url_from_config(str(home))
    if configured:
        return configured
    # RoomLink is a gateway reachability property, not a Bot personality
    # setting: named profiles may override it but otherwise inherit the process
    # gateway's root endpoint, so adding a Bot needs no repeated network config.
    root = get_default_hermes_root()
    return _room_link_url_from_config(str(root)) if root != home else None


def validate_room_link_url(value: Any) -> tuple[str, TransportSecurity]:
    """Validate a RoomLink endpoint and classify its transport protection.

    Plaintext HTTP is allowed only toward the local loopback interface; every
    non-loopback endpoint must use HTTPS.
    """
    raw = str(value or "").strip().rstrip("/")
    try:
        parsed = urllib.parse.urlsplit(raw)
        hostname = (parsed.hostname or "").rstrip(".").lower()
        # Force urllib to validate a malformed/out-of-range port.
        parsed.port
    except ValueError as exc:
        raise HostedRoomPeerError("target_url is invalid") from exc
    if not hostname or parsed.username is not None or parsed.password is not None:
        raise HostedRoomPeerError("target_url is invalid")
    if parsed.query or parsed.fragment:
        raise HostedRoomPeerError("target_url must not include query or fragment")
    if parsed.scheme.lower() == "https":
        return raw, "tls"
    if parsed.scheme.lower() != "http":
        raise HostedRoomPeerError("target_url must use https")

    loopback = hostname == "localhost" or hostname.endswith(".localhost")
    if not loopback:
        try:
            loopback = ipaddress.ip_address(hostname).is_loopback
        except ValueError:
            loopback = False
    if not loopback:
        raise HostedRoomPeerError("target_url must use https outside the local machine")
    return raw, "loopback"


# Validator per dispatch field, in validation order. ``prompt`` and
# ``prompt_digest`` are checked together against each other in from_mapping.
_DISPATCH_FIELDS: dict[str, Callable[..., Any]] = dict(
    protocol_version=_positive_int, room_id=_identifier, home_install_id=_identifier,
    authority_gateway_id=_identifier, authority_epoch=_positive_int, member_id=_identifier,
    target_install_id=_identifier, target_profile=_identifier, task_id=_identifier,
    execution_generation=_positive_int, source_event_seq=_positive_int, cancellation_scope_id=_identifier,
    capability_digest=_digest, execution_policy_digest=_digest, trace_id=_identifier,
)


@dataclass(frozen=True)
class HostedMemberDispatch:
    """Recipient-validated identity for one remote room member attempt."""

    protocol_version: int
    room_id: str
    home_install_id: str
    authority_gateway_id: str
    authority_epoch: int
    member_id: str
    target_install_id: str
    target_profile: str
    task_id: str
    execution_generation: int
    source_event_seq: int
    cancellation_scope_id: str
    prompt: str
    prompt_digest: str
    capability_digest: str
    execution_policy_digest: str
    trace_id: str

    def as_mapping(self) -> dict[str, Any]:
        """Return the canonical wire mapping used for fingerprinting."""
        return asdict(self)

    @classmethod
    def from_mapping(cls, value: Mapping[str, Any]) -> "HostedMemberDispatch":
        _exact_fields(value, required=set(_DISPATCH_FIELDS) | {"prompt", "prompt_digest"}, label="dispatch")
        prompt = value["prompt"]
        if not isinstance(prompt, str) or not prompt.strip():
            raise HostedRoomPeerError("prompt must be a non-empty string")
        if len(prompt.encode("utf-8")) > MAX_PROMPT_BYTES:
            raise HostedRoomPeerError("prompt is too large")
        expected_prompt_digest = hashlib.sha256(prompt.encode("utf-8")).hexdigest()
        prompt_digest = _digest(value["prompt_digest"], field="prompt_digest")
        if not hmac.compare_digest(expected_prompt_digest, prompt_digest):
            raise HostedRoomPeerError("prompt_digest does not match prompt")
        return cls(
            prompt=prompt, prompt_digest=prompt_digest,
            **{name: check(value[name], field=name) for name, check in _DISPATCH_FIELDS.items()},
        )


# Grant scope fields, in issue-time validation order; each is validated with
# the same checker as the matching dispatch field (``grant_id`` is an identifier).
_GRANT_SCOPE = (
    "grant_id", "room_id", "home_install_id", "authority_gateway_id", "authority_epoch",
    "member_id", "target_install_id", "target_profile",
)
_GRANT_FIELDS = frozenset({
    "version", *_GRANT_SCOPE, "execution_policy_digest", "permissions", "issued_at", "expires_at",
})
_GRANT_REFRESH_FIELDS = _GRANT_FIELDS | {"status_expires_at"}
_GRANT_PERMISSIONS = {"approve", "dispatch", "status", "stop"}
MAX_DISPATCH_GRANT_TTL_SECONDS = 24 * 60 * 60
MAX_STATUS_GRANT_TTL_SECONDS = 30 * 24 * 60 * 60


def issue_room_grant(
    secret: bytes, *, grant_id: str, room_id: str, home_install_id: str, authority_gateway_id: str,
    authority_epoch: int, member_id: str, target_install_id: str, target_profile: str,
    execution_policy_digest: str | None = None,
    permissions: Iterable[str] = ("approve", "dispatch", "status", "stop"),
    issued_at: float | None = None, ttl_seconds: float = 3600, status_ttl_seconds: float | None = None,
    status_expires_at: float | None = None,
) -> str:
    """Issue a target-verifiable bearer grant scoped to one room member."""
    if len(secret) < 32:
        raise HostedRoomGrantError("room grant secret must be at least 32 bytes")
    now = time.time() if issued_at is None else float(issued_at)
    bounded_status_expiry = (
        now + float(ttl_seconds if status_ttl_seconds is None else status_ttl_seconds)
        if status_expires_at is None
        else float(status_expires_at)
    )
    if (
        not math.isfinite(now) or ttl_seconds <= 0 or ttl_seconds > MAX_DISPATCH_GRANT_TTL_SECONDS
        or not math.isfinite(bounded_status_expiry) or bounded_status_expiry < now + float(ttl_seconds)
        or bounded_status_expiry > now + MAX_STATUS_GRANT_TTL_SECONDS
    ):
        raise HostedRoomGrantError("room grant lifetime is invalid")
    allowed = tuple(sorted(set(permissions)))
    if not allowed or not set(allowed) <= _GRANT_PERMISSIONS:
        raise HostedRoomGrantError("room grant permissions are invalid")
    scope = {
        "grant_id": grant_id, "room_id": room_id, "home_install_id": home_install_id,
        "authority_gateway_id": authority_gateway_id, "authority_epoch": authority_epoch,
        "member_id": member_id, "target_install_id": target_install_id, "target_profile": target_profile,
    }
    payload = {
        "version": PROTOCOL_VERSION,
        **{name: _DISPATCH_FIELDS.get(name, _identifier)(scope[name], field=name) for name in _GRANT_SCOPE},
        "execution_policy_digest": _digest(
            execution_policy_digest
            or execution_policy_mapping(target_profile=target_profile)["policy_digest"],
            field="execution_policy_digest",
        ),
        "permissions": list(allowed), "issued_at": now, "expires_at": now + float(ttl_seconds),
        "status_expires_at": bounded_status_expiry,
    }
    encoded = _canonical_json(payload)
    signature = hmac.new(secret, encoded, hashlib.sha256).digest()
    token = f"{_b64encode(encoded)}.{_b64encode(signature)}"
    if len(token.encode("ascii")) > MAX_TOKEN_BYTES:
        raise HostedRoomGrantError("room grant is too large")
    return token


def verify_room_grant(
    secret: bytes, token: str, dispatch: HostedMemberDispatch, *, permission: str = "dispatch",
    now: float | None = None,
) -> dict[str, Any]:
    """Verify one room grant against exact recipient dispatch coordinates."""
    payload = decode_room_grant(secret, token, permission=permission, now=now)
    if payload["version"] != dispatch.protocol_version:
        raise HostedRoomGrantError("room grant protocol does not match dispatch")
    scope = (*_GRANT_SCOPE[1:], "execution_policy_digest")
    if any(payload.get(field) != getattr(dispatch, field) for field in scope):
        raise HostedRoomGrantError("room grant scope does not match dispatch")
    return payload


def decode_room_grant(
    secret: bytes, token: str, *, permission: str, now: float | None = None
) -> dict[str, Any]:
    """Verify grant signature, lifetime and operation without a dispatch."""
    if not isinstance(token, str) or len(token.encode("utf-8")) > MAX_TOKEN_BYTES:
        raise HostedRoomGrantError("room grant is invalid")
    encoded_token, signature_token = _split_token(token)
    encoded = _b64decode(encoded_token)
    supplied_signature = _b64decode(signature_token)
    expected_signature = hmac.new(secret, encoded, hashlib.sha256).digest()
    if not hmac.compare_digest(expected_signature, supplied_signature):
        raise HostedRoomGrantError("room grant signature is invalid")
    try:
        payload = json.loads(encoded.decode("ascii"))
    except Exception as exc:
        raise HostedRoomGrantError("room grant payload is invalid") from exc
    if not isinstance(payload, dict) or frozenset(payload) not in {_GRANT_FIELDS, _GRANT_REFRESH_FIELDS}:
        raise HostedRoomGrantError("room grant fields are invalid")
    checked_now = time.time() if now is None else float(now)
    if not math.isfinite(checked_now):
        raise HostedRoomGrantError("room grant clock is invalid")
    try:
        issued_at = float(payload["issued_at"])
        expires_at = float(payload["expires_at"])
        status_expires_at = float(payload.get("status_expires_at", expires_at))
    except (TypeError, ValueError) as exc:
        raise HostedRoomGrantError("room grant lifetime is invalid") from exc
    finite = all(map(math.isfinite, (issued_at, expires_at, status_expires_at)))
    if not (finite and issued_at < expires_at <= status_expires_at):
        raise HostedRoomGrantError("room grant lifetime is invalid")
    operation_expires_at = status_expires_at if permission in {"approve", "status", "stop"} else expires_at
    if checked_now < issued_at - 30 or checked_now >= operation_expires_at:
        raise HostedRoomGrantError("room grant is expired or not active")
    permissions = payload.get("permissions")
    if not isinstance(permissions, list) or permission not in permissions:
        raise HostedRoomGrantError("room grant does not allow this operation")
    return payload


def room_grant_needs_dispatch_refresh(
    token: str, *, now: float | None = None, leeway_seconds: float = 5 * 60
) -> bool:
    """Read only grant timing to schedule target-validated refresh.

    This deliberately does not establish trust; the target validates the
    signature and immutable scope before issuing a replacement.
    """
    try:
        payload = json.loads(_b64decode(_split_token(token)[0]).decode("ascii"))
        expires_at = float(payload["expires_at"])
        checked_now = time.time() if now is None else float(now)
        return checked_now + max(0.0, float(leeway_seconds)) >= expires_at
    except Exception:
        return True