Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

16.1 KB
Raw Blame
"""Scoped agent-addressing permissions (CHOO-1585).

Controls WHO may *address* an agent — i.e. cause it to receive a message it is
expected to respond to (an `@name` / `@alias` / `@role` mention or a targeted
message). An agent with no policy is open to any room
participant; this module adds a per-agent allow-list model.

Model:
  - Each agent carries an `AddressingPolicy`: an ordered list of allow-rules.
  - A rule constrains four dimensions of the *incoming* addressing attempt:
      * `rooms`       — the room the message is in
      * `room_groups` — the group that room belongs to (``None`` if ungrouped)
      * `users`       — matched when the sender is a human
      * `agents`      — matched when the sender is another agent
  - Each dimension is either ``"*"`` (any), or an explicit list of ids. An
    empty list ``[]`` is the "none" value: it matches nothing. The sender is
    exactly one kind (user, agent, or platform), so a rule that should admit
    only humans sets ``agents: []`` and vice-versa.
  - A rule carries a ``platform`` boolean. When True, the rule admits the
    Switch platform as a sender. Platform is denied by default, even by an
    open policy (no rules), so an agent must opt in with ``platform=True``.
  - A rule additionally carries two *symbolic* subjects (CHOO-2137), resolved
    at enforcement time rather than stored as ids, so they survive the owner
    claiming a new platform identity, a bridge being recreated, or the agent
    changing hands:
      * `owner`        — the agent's own owner, whoever that currently is.
                         Human senders only.
      * `owner_agents` — any agent owned by that same person. Agent senders
                         only. This is what keeps an owner's own orchestration
                         working under an owner-scoped policy: the manager
                         dispatching a worker is the owner acting through a
                         program, and naming each agent by id would break the
                         moment they register a new one.
    Both are per-rule, so they carry that rule's room scoping like any other
    dimension.
  - A rule *allows* an attempt when the context matches (room AND group) AND
    the sender matches (its own kind's dimension, or `owner` for a human).
    Addressing is permitted when **any** rule allows it.

Defaults / precedence:
  - An agent with **no rules** is open: anyone may address it. This is what a
    pre-CHOO-2137 agent carries, and it is preserved rather than migrated.
  - With rules present it is **deny-by-default**: only attempts matching a rule
    are permitted.
  - New agents start on `default_agent_policy`: their owner and the owner's
    own agents, rather than open. Agents created earlier keep whatever policy
    they were created with.
  - **Platform senders are always deny-by-default**, even for an open
    policy. An agent needs a rule with ``platform=True`` to receive the
    platform's own messages. A platform message sent on a person's behalf is
    judged as that person instead (`allows_on_behalf_of`), so the platform
    never reaches an agent the person could not.

This module is deliberately pure (no DB, no I/O) so it is trivially testable
and reusable from the receive path, the protocol service, and the gateway.
"""

from __future__ import annotations

from typing import Literal

from pydantic import BaseModel, field_validator

SenderKind = Literal["user", "agent", "platform"]

ANY = "*"

# A dimension is "*" (any) or an explicit list of ids ([] = none / match nothing).
Dimension = str | list[str]


class AddressingRule(BaseModel):
    """One allow-rule. An attempt is allowed when it matches this rule on all
    four dimensions (see module docstring). Each dimension defaults to ``"*"``
    (unconstrained); note that leaving ``users``/``agents`` at ``"*"`` admits
    that whole sender kind — set the one you want to exclude to ``[]``."""

    rooms: Dimension = ANY
    room_groups: Dimension = ANY
    users: Dimension = ANY
    agents: Dimension = ANY
    owner: bool = False
    owner_agents: bool = False
    platform: bool = False

    @field_validator("rooms", "room_groups", "users", "agents")
    @classmethod
    def _valid_dimension(cls, value: Dimension) -> Dimension:
        if value == ANY:
            return value
        if isinstance(value, list) and all(isinstance(v, str) for v in value):
            return value
        raise ValueError(f'dimension must be "*" or a list of ids, got {value!r}')

    def _matches(
        self,
        *,
        room_id: str,
        group_id: str | None,
        sender_kind: SenderKind,
        sender_id: str,
        sender_user_ids: list[str],
        sender_owner_user_id: str | None,
        owner_user_id: str | None,
    ) -> bool:
        if not _dim_contains(self.rooms, room_id):
            return False
        if not _dim_contains(self.room_groups, group_id):
            return False
        if sender_kind == "platform":
            return self.platform
        if sender_kind == "user" and self._is_owner(sender_user_ids, owner_user_id):
            return True
        if sender_kind == "agent" and self._is_owners_agent(
            sender_owner_user_id, owner_user_id
        ):
            return True
        sender_dim = self.users if sender_kind == "user" else self.agents
        return _dim_contains(sender_dim, sender_id)

    def _is_owner(self, sender_user_ids: list[str], owner_user_id: str | None) -> bool:
        """Whether this rule admits the sender as the agent's owner.

        A platform account may be claimed by several Switch users, so the
        sender arrives as the set of users who say it is theirs; the owner
        need only be among them. An ownerless agent has no owner to match, and
        an unclaimed account resolves to nobody — both answer "not the owner"
        rather than making a permissive guess.
        """
        if not self.owner:
            return False
        if owner_user_id is None:
            return False
        return owner_user_id in sender_user_ids

    def _is_owners_agent(
        self, sender_owner_user_id: str | None, owner_user_id: str | None
    ) -> bool:
        """Whether this rule admits the sender as an agent of the same owner.

        Both sides must be owned for this to mean anything: two ownerless
        agents are not each other's, and an ownerless target has nobody whose
        agents these would be. Either one missing answers "no" rather than
        letting an unowned agent inherit the fleet's trust.
        """
        if not self.owner_agents:
            return False
        if owner_user_id is None or sender_owner_user_id is None:
            return False
        return sender_owner_user_id == owner_user_id


def never_allows(rule: AddressingRule) -> str | None:
    """Why `rule` can never allow anyone, or None when it can.

    With rules present a policy denies whatever no rule allows, so a rule like
    this allows nothing while looking as if it did, and a policy of nothing
    but such rules shuts the agent off, its owner included. Checked when a
    policy is saved (`gateway/agents.py`), not when one is read: one stored
    before still parses.
    """
    if rule.rooms == []:
        return "it names no rooms"
    if rule.room_groups == []:
        return "it names no room groups"
    if (
        rule.users == []
        and rule.agents == []
        and not (rule.owner or rule.owner_agents or rule.platform)
    ):
        return "it lets in no people, no agents, not the owner and not the platform"
    return None


class AddressingPolicy(BaseModel):
    """An agent's addressing allow-list. Empty ``rules`` → allow-all."""

    rules: list[AddressingRule] = []

    def is_open(self) -> bool:
        """True when the policy imposes no restriction (no rules)."""
        return not self.rules

    def allows(
        self,
        *,
        room_id: str,
        group_id: str | None,
        sender_kind: SenderKind,
        sender_id: str,
        sender_user_ids: list[str],
        sender_owner_user_id: str | None,
        owner_user_id: str | None,
    ) -> bool:
        """Whether an addressing attempt from this sender, in this room, is
        permitted. Allow-all when the policy is open; otherwise permitted iff
        at least one rule matches.

        Platform senders are denied even by an open policy; an agent must opt
        in with a rule that sets ``platform=True``.

        `sender_user_ids` are the Switch users who have claimed a human
        sender's platform account (empty when nobody has);
        `sender_owner_user_id` is who owns an agent sender (None for a human
        or an ownerless agent); `owner_user_id` is the addressed agent's
        owner. Together they resolve the `owner` and `owner_agents` rules.
        """
        if self.is_open() and sender_kind != "platform":
            return True
        return any(
            rule._matches(
                room_id=room_id,
                group_id=group_id,
                sender_kind=sender_kind,
                sender_id=sender_id,
                sender_user_ids=sender_user_ids,
                sender_owner_user_id=sender_owner_user_id,
                owner_user_id=owner_user_id,
            )
            for rule in self.rules
        )

    def admits_others(self, *, owner_identity_ids: set[str]) -> bool:
        """Whether anyone but the owner may address the agent, and so have it
        act on what its owner granted it.

        An open policy does; so does any rule that admits every human
        (``"*"``, whatever its rooms), a human by an identity the owner has
        not claimed, or any agent named by id or ``"*"``. The owner's own
        agents (``owner_agents``) do not count: they already act for the
        owner, so the default policy raises no warning. `owner_identity_ids`
        are the platform identities the owner has claimed. A platform rule is
        not counted: the platform acting for a person is judged as that person
        (`allows_on_behalf_of`).

        This only reports the exposure; it does not refuse anything.
        """
        if self.is_open():
            return True
        return any(
            _admits_beyond(rule.users, owner_identity_ids) or rule.agents != []
            for rule in self.rules
        )

    def requires_owner_identity(self) -> bool:
        """Whether any rule depends on resolving the owner's platform identity.

        Used to warn an operator that an agent is unreachable until its owner
        claims an identity on the bridges it works over — the difference
        between a policy that is merely strict and one that admits nobody.
        """
        return any(rule.owner for rule in self.rules)


def _dim_contains(dimension: Dimension, value: str | None) -> bool:
    """Whether a single dimension admits ``value``. ``"*"`` admits anything;
    a list admits only its members; ``None`` (e.g. an ungrouped room) is admitted
    only by ``"*"``."""
    if dimension == ANY:
        return True
    if value is None:
        return False
    return value in dimension


def _admits_beyond(dimension: Dimension, own: set[str]) -> bool:
    """Whether a sender dimension admits anyone outside `own`."""
    return dimension == ANY or any(value not in own for value in dimension)


def parse_policy(raw: dict | None) -> AddressingPolicy:
    """Build a policy from a stored JSONB blob (``None`` → open policy)."""
    if not raw:
        return AddressingPolicy()
    return AddressingPolicy.model_validate(raw)


def owner_only_policy(allowed_agent_ids: list[str]) -> AddressingPolicy:
    """Owner-only: the agent's owner anywhere, and nobody else.

    No other human, and no agent except those explicitly granted.
    `allowed_agent_ids` names individual dispatchers by id; empty means the
    agent answers only to its owner, in person.
    """
    return AddressingPolicy(
        rules=[
            AddressingRule(
                rooms=ANY,
                room_groups=ANY,
                users=[],
                agents=list(allowed_agent_ids),
                owner=True,
            )
        ]
    )


def owner_and_owner_agents_policy() -> AddressingPolicy:
    """The owner, plus any agent that owner runs (CHOO-2137).

    What every new agent starts on (`default_agent_policy`). Strict owner-only
    is one step too strict to be the thing everyone starts on: an owner's
    manager agent dispatching their worker is still the owner acting, and an
    agent that refuses its own owner's orchestration looks broken rather than
    private. Somebody else's agent is admitted by neither.
    """
    return AddressingPolicy(
        rules=[
            AddressingRule(
                rooms=ANY,
                room_groups=ANY,
                users=[],
                agents=[],
                owner=True,
                owner_agents=True,
            )
        ]
    )


def default_agent_policy() -> AddressingPolicy:
    """The policy a new agent gets when its creator makes no choice.

    The one place the default is decided: registration, `create_agent`,
    template runs and Switch Console all start from it. Agents that already
    exist keep the policy they were created with.
    """
    return owner_and_owner_agents_policy()


AddressingKind = Literal["owner_only", "owner_and_owner_agents", "anyone", "custom"]


def policy_kind(raw: dict | None) -> AddressingKind:
    """Which of the choices Switch Console offers a stored policy is.

    "owner_only", "owner_and_owner_agents" and "anyone" are the three
    shortcuts; "custom" is every other rule set, including owner-only with
    agents granted by id. "anyone" is an open policy, which still turns the
    platform's own messages away.
    """
    policy = parse_policy(raw)
    if policy.is_open():
        return "anyone"
    if policy == owner_only_policy([]):
        return "owner_only"
    if policy == owner_and_owner_agents_policy():
        return "owner_and_owner_agents"
    return "custom"


def platform_allowed_policy() -> AddressingPolicy:
    """A policy that admits the platform sender.

    Returns a single rule allowing ``platform`` in any room. Combine with
    owner/agent rules by appending to their rule list rather than replacing
    their policy with this one.
    """
    return AddressingPolicy(
        rules=[
            AddressingRule(
                rooms=ANY,
                room_groups=ANY,
                users=[],
                agents=[],
                platform=True,
            )
        ]
    )


def allows_on_behalf_of(
    policy: AddressingPolicy,
    *,
    room_id: str,
    group_id: str | None,
    user_id: str,
    external_user_ids: list[str],
    owner_user_id: str | None,
) -> bool:
    """Whether the platform may address this agent with `user_id`'s authority.

    The answer is exactly what the policy would say to that person speaking
    in the room themselves: an open policy admits them, an owner rule admits
    them when they own the agent, and a ``users`` list admits them when one
    of the platform accounts they have claimed (`external_user_ids`) is in
    it. A person with no claimed account can still pass ``users: "*"`` and an
    owner rule, which is what they could do as a human sender too.
    """
    if policy.is_open():
        return True
    candidates = external_user_ids or [""]
    return any(
        policy.allows(
            room_id=room_id,
            group_id=group_id,
            sender_kind="user",
            sender_id=external_id,
            sender_user_ids=[user_id],
            sender_owner_user_id=None,
            owner_user_id=owner_user_id,
        )
        for external_id in candidates
    )


def can_address(
    policy: AddressingPolicy,
    *,
    room_id: str,
    group_id: str | None,
    sender_kind: SenderKind,
    sender_id: str,
    sender_user_ids: list[str],
    sender_owner_user_id: str | None,
    owner_user_id: str | None,
) -> bool:
    """Convenience free function mirroring :meth:`AddressingPolicy.allows`."""
    return policy.allows(
        room_id=room_id,
        group_id=group_id,
        sender_kind=sender_kind,
        sender_id=sender_id,
        sender_user_ids=sender_user_ids,
        sender_owner_user_id=sender_owner_user_id,
        owner_user_id=owner_user_id,
    )