capabilities

capabilities

What a device may be asked to do — and who decides.

The rule this module exists to enforce (spec §6, acceptance TEST I): a device DECLARES its capabilities, the server GRANTS them. A declaration is information, never authorisation. A compromised or lying agent that claims automation.approved.run on an iPhone must not receive it, because the platform cannot honour it and no amount of insistence changes that.

So every capability passes through two gates:

1. PLATFORM_CAPABILITIES — what the operating system can actually do. This is the honest matrix of spec §26, written once, server-side.
2. the device's own declaration — what this build actually implements, which is always a SUBSET of what its platform allows.

Effective = intersection. Never the union, never the claim alone.

Functions:

local_capabilities

local_capabilities() -> frozenset[str]

What THIS machine may honour, from its own platform ceiling.

The receiver's authority on itself. Deliberately independent of the registry: a device is never listed in its own registry, so a receiver that looked itself up there found nothing and silently allowed everything. Asking a peer what we are permitted to do would be asking the wrong party anyway — it is the party whose record an attacker would have tampered with.

Source code in src/diapason/mesh/capabilities.py

def local_capabilities() -> frozenset[str]:
    """What THIS machine may honour, from its own platform ceiling.

    The receiver's authority on itself. Deliberately independent of the
    registry: a device is never listed in its own registry, so a receiver
    that looked itself up there found nothing and silently allowed
    everything. Asking a peer what we are permitted to do would be asking
    the wrong party anyway — it is the party whose record an attacker would
    have tampered with.
    """
    from diapason.mesh.identity import device_identity
    from diapason.mesh.tools import list_remote_tools

    catalogue = [tool["capability"] for tool in list_remote_tools()]
    return frozenset(effective_capabilities(device_identity().platform, catalogue))

effective_capabilities

effective_capabilities(
    platform: str, declared: Iterable[str] | None
) -> tuple[str, ...]

The capabilities a device actually gets, sorted and deduplicated.

Unknown verbs are dropped rather than rejected: a newer client that declares a capability this server has never heard of should keep working for everything else it declared, not fail wholesale.

Source code in src/diapason/mesh/capabilities.py

def effective_capabilities(
    platform: str, declared: Iterable[str] | None
) -> tuple[str, ...]:
    """The capabilities a device actually gets, sorted and deduplicated.

    Unknown verbs are dropped rather than rejected: a newer client that
    declares a capability this server has never heard of should keep working
    for everything else it declared, not fail wholesale.
    """
    ceiling = PLATFORM_CAPABILITIES.get(
        (platform or "").upper(), PLATFORM_CAPABILITIES["UNKNOWN"]
    )
    claimed = {str(c).strip() for c in (declared or []) if str(c).strip()}
    return tuple(sorted(claimed & ceiling))