What it provides

• Async-first Python API — create_notifier(), Notifier protocol, DbusNotifier, CallbackNotifier, NullNotifier
• Varlink hub — ClearanceHub, ClearanceClient, EventSubscriber — the subscriber API operator UIs build on (the TUI renders live verdicts through it)
• Multi-socket subscriber — MultiSocketSubscriber multiplexes the per-container hub sockets at $XDG_RUNTIME_DIR/terok/clearance/<short_id>/hub.sock so a single UI sees the union of every supervisor's event stream
• Embeddable verdict server — VerdictServer for the per-container supervisor to compose alongside the hub
• Graceful degradation — NullNotifier is returned when no D-Bus session bus is available, so headless hosts can still run the rest of the stack

Where it sits in the stack

terok-clearance is the user-in-the-loop side-rail of the terok ecosystem. Above it, terok's TUI subscribes to every per-container hub socket to display verdicts in-band; on a desktop session the same events fire freedesktop popups. Below it, the verdict server reaches into terok-shield to mutate the running ruleset. Lifecycle is owned by terok-sandbox's per-container supervisor, which composes the hub and verdict server in-process for every container it watches.

The notification API (create_notifier(), the Notifier protocol) is usable standalone for generic desktop-notification needs.

Requirements

• Linux with a D-Bus session bus (any desktop environment with a notification daemon) — the package degrades cleanly to a no-op notifier when no bus is reachable
• Python 3.12+

Installation

pip install terok-clearance

For most users this dependency is pulled in transitively by terok-sandbox. Install it directly only when embedding the API in your own tooling.

Quick start

Send a notification

import asyncio
from terok_clearance import create_notifier


async def main():
    notifier = await create_notifier(app_name="terok")
    action_received = asyncio.Event()

    def on_action(action_key):
        print(action_key)
        action_received.set()

    nid = await notifier.notify(
        "Clearance request",
        "Task alpha wants access to api.github.com:443",
        actions=[("allow", "Allow"), ("deny", "Deny")],
    )
    await notifier.on_action(nid, on_action)

    await action_received.wait()
    await notifier.disconnect()


asyncio.run(main())

CLI tool (development / testing)

terok-clearance-hub notify "Title" "Body"   # one-shot desktop notification
terok-clearance-hub serve                   # run a clearance hub
terok-clearance-hub serve-verdict           # run the verdict helper
terok-clearance-hub clearance               # interactive terminal UI

License

Apache-2.0 — see LICENSES/Apache-2.0.txt.