289 lines
16 KiB
Markdown
289 lines
16 KiB
Markdown
# Mobile Connector Plugin (`mobile-connector`)
|
|
|
|
Bridges Skald's **Inbox** (approvals + clarifications + MCP elicitations) to mobile apps over the
|
|
**relay**, implementing the **agent** role of the v2 relay protocol. The plugin is
|
|
the namespace owner and the sole authority over authorized devices. Skald is
|
|
never exposed on the internet: only this plugin connects out, and only to the
|
|
relay.
|
|
|
|
- Crate: `crates/plugin-mobile-connector` — the **application** layer (thin).
|
|
- Networking: `crates/skald-relay-client` — the **standalone, payload-agnostic**
|
|
relay client (WS v2 transport, E2E crypto, anti-replay counters, pairing,
|
|
device authorization, SQLite persistence). It depends only on
|
|
`skald-relay-common` (never on `core-api`), so it is reusable and unit/
|
|
integration-tested in isolation. See [Crate split](#crate-split-skald-relay-client).
|
|
- Shared crypto + protobuf: `crates/skald-relay-common` (byte-for-byte interop
|
|
with the reference vectors in [relay/test-vectors.md](../relay/test-vectors.md))
|
|
- **Protocol documentation** (canonical, in English):
|
|
- [relay/index.md](../relay/index.md) — architecture, actors, threat model
|
|
- [relay/relay-protocol.md](../relay/relay-protocol.md) — protobuf schema, auth, pairing, live channel, presence
|
|
- [relay/framing.md](../relay/framing.md) — E2E plaintext framing (version + compression)
|
|
- [relay/payloads.md](../relay/payloads.md) — JSON payload schemas (inbox_request, inbox_update, …)
|
|
- [relay/crypto.md](../relay/crypto.md) — crypto contract, key derivation, AEAD, anti-replay
|
|
|
|
---
|
|
|
|
## Crate split: skald-relay-client
|
|
|
|
The plugin is the **application** layer; all networking lives in the standalone
|
|
`skald-relay-client` crate. The boundary is **payload-agnostic**: the client
|
|
exchanges opaque decrypted `Vec<u8>` payloads keyed by device pubkey and emits
|
|
inbound traffic as `RelayEvent`s; it never interprets the JSON. The plugin
|
|
consumes `client.events()`, applies the JSON schemas (`payloads.rs`) and the
|
|
`InboxApi`, and calls `client.send(dest, bytes, live)`.
|
|
|
|
Consequences of the split:
|
|
|
|
- **Authorization policy stays in the plugin.** On `RelayEvent::ClientPaired`,
|
|
the client has already derived the `aes_key`, persisted the device as Pending,
|
|
and consumed the pairing token. The plugin's event loop decides: if
|
|
`require_device_confirmation` it notifies; otherwise it calls
|
|
`client.authorize(ed)` and then `broadcast_inbox()`.
|
|
- **`client.authorize()` is payload-agnostic** — it does NOT push an Inbox
|
|
snapshot. The plugin sends the snapshot after authorizing (both the auto path
|
|
and the `RelayAgent::authorize_client` tool path).
|
|
- **v2 framing (`compress/decompress_payload`) is transport** — handled inside
|
|
the client, so the plugin only ever sees clean JSON.
|
|
- **Identity seed** is injected via `SeedSource::Path("data/relay/seed")` (same
|
|
relative path as before) so existing identities/devices survive the upgrade.
|
|
|
|
### Module map — `skald-relay-client` (networking)
|
|
|
|
| Module | Role |
|
|
|---|---|
|
|
| `config.rs` | `RelayClientConfig` + `SeedSource` (`Bytes` / `Path`) |
|
|
| `events.rs` | `RelayEvent` (`Connected`/`Disconnected`/`Message`/`ClientPaired`/`ClientRevoked`), broadcast |
|
|
| `identity.rs` | Seed load/generate (`0600`, injected path) + derived Ed25519/X25519 keys + `namespace_id` |
|
|
| `db.rs` | `relay_clients` table — devices + anti-replay counters (atomic counter helpers, `delete_all`) |
|
|
| `pairing.rs` | In-memory single-window pairing sessions (`code → session`) + `QrCodeData` |
|
|
| `state.rs` | Networking-only runtime: per-client `aes_key` cache, seal/open, counters, emits events |
|
|
| `ws.rs` | Permanent reconnecting agent WebSocket (v2 binary transport). Challenge → `Auth` → role dispatch → forward loop |
|
|
| `client.rs` | `RelayClient` — the public façade (`new`/`start`/`shutdown`/`send`/pairing/authorize/revoke/`clear_all`/`events`) |
|
|
|
|
### Module map — `plugin-mobile-connector` (application)
|
|
|
|
| Module | Role |
|
|
|---|---|
|
|
| `payloads.rs` | E2E JSON payload schemas (`inbox_update`, `notification`, client responses incl. `inbox_request`). Zlib-compressible per v2 framing.md |
|
|
| `app.rs` | `RelayApp`: Inbox dispatch (`broadcast_inbox`/`apply_client_payload`), authorization policy, the `events()` consumer loop |
|
|
| `notifier.rs` | `DelayedNotifier`: debounces phone pushes (`notify_delay_secs`) so resolving on the computer suppresses the push. See [Delayed push](#delayed-push) |
|
|
| `proxy.rs` | Accepts relay **pipes** of `stream_type = "http-local-proxy"` and reverse-proxies each to `127.0.0.1:<web_port>`. See [HTTP reverse proxy](#http-reverse-proxy-http-local-proxy) |
|
|
| `router.rs` | The QR-code HTTP endpoint (`/pairingqrcode`), resolves the current `RelayApp` → `client.lookup_pairing` |
|
|
| `agent.rs` | `RelayAgent` control trait (pairing, list, authorize, revoke) |
|
|
| `tools.rs` | The three LLM tools, registered in the main crate's `ToolRegistry` |
|
|
| `lib.rs` | `MobileConnectorPlugin` (`Plugin` + `RelayAgent`), lifecycle, bus subscriber, `RelayClient`/`RelayApp` wiring |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Stored in the `plugins` table (JSON, edited via the plugin UI / `configure_plugin`):
|
|
|
|
```yaml
|
|
relay_url: "wss://relay.skaldagent.net/v1/ws" # empty ⇒ plugin idle (no WS)
|
|
pairing_ttl: 300 # seconds, max 600
|
|
require_device_confirmation: true # manual confirm new devices (recommended)
|
|
notify_delay_secs: 20 # debounce before pushing to the phone (0 = immediate)
|
|
```
|
|
|
|
`enabled` (the standard plugin flag) starts/stops the runloop.
|
|
|
|
`notify_delay_secs` debounces the **phone push** for a new approval/clarification
|
|
(see [Delayed push](#delayed-push)). The mobile push is only useful when you're
|
|
away from the computer; if you answer at the computer within the window, no phone
|
|
notification is sent. Set `0` to push immediately.
|
|
|
|
---
|
|
|
|
## Persistence (plugin.md §9)
|
|
|
|
| Data | Location | Why |
|
|
|---|---|---|
|
|
| `seed` (32 B) | filesystem `data/relay/seed`, `0600` | the only persistent secret; keys + `namespace_id` are derived at runtime |
|
|
| Pairing session | **in-memory** only | transient (≤ TTL); lost on restart ⇒ just re-pair |
|
|
| Devices + `send/recv_counter` | DB `relay_clients` | **must** survive restarts |
|
|
|
|
### Why counters live in the DB
|
|
|
|
Skald self-restarts by design. If counters reset to 0 on restart:
|
|
- `send_counter → 0` reuses an AES-GCM nonce under the same key (breaks
|
|
confidentiality + integrity for that device).
|
|
- `recv_counter → 0` re-opens the replay window.
|
|
|
|
So `send_counter` is incremented **and persisted before** sealing/sending
|
|
(`db::next_send_counter`, a transaction), and `recv_counter` is persisted only
|
|
**after** a valid `open`.
|
|
|
|
### `aes_key` cache
|
|
|
|
The per-client AES-256-GCM key is `HKDF(X25519(seed_x_priv, client_x_pub))`. It
|
|
is derived once and cached in memory (`HashMap<ed25519_pub, aes_key>` in
|
|
`RelayState`), never persisted; on a cache miss it is re-derived from the
|
|
client's stored `x25519_pub`. The cache entry is dropped on revoke.
|
|
|
|
---
|
|
|
|
## Pairing flow
|
|
|
|
1. The agent calls `mobile_start_pairing(ttl?)` (gated behind approval).
|
|
2. The plugin generates a 32-byte `pairing_token` (CSPRNG), sends
|
|
`pairing_start{token, ttl}` to the relay, and registers an in-memory session
|
|
keyed by a separate random `code` (latest-wins: any prior active session is
|
|
marked *Superseded*). It returns the URL
|
|
`/api/plugin/mobile-connector/pairingqrcode?code=<code>`.
|
|
3. The copilot renders the URL as an image. The endpoint serves a PNG of the QR
|
|
while the session is **Active**, else a placeholder (`QR scaduto` /
|
|
`QR già usato`). The QR payload is the normative `QrCodeData` JSON (never on
|
|
disk, never in the URL).
|
|
4. The client scans, connects as `role:"pairing"`, the relay consumes the token
|
|
and forwards `client_paired` to the agent.
|
|
5. On `client_paired`: derive + cache `aes_key`, persist the client as
|
|
**Pending** (counters 0), mark the session **Consumed**, then apply the
|
|
policy:
|
|
- `require_device_confirmation = false` ⇒ auto-authorize.
|
|
- `require_device_confirmation = true` ⇒ leave Pending; the human authorizes
|
|
via the control surface (a `notification` is pushed to existing devices).
|
|
|
|
`authorize` always reflects the full local set (replacement semantics): adding a
|
|
device sends the complete list including it; revoking sends it without.
|
|
|
|
---
|
|
|
|
## Message flows
|
|
|
|
- **Inbox → clients:** the bus subscriber reacts to the six Inbox events
|
|
(`approval_requested`, `approval_resolved`, `clarification_requested`,
|
|
`clarification_resolved`, `elicitation_requested`, `elicitation_resolved`) and
|
|
routes them through the **debouncer** (see
|
|
[Delayed push](#delayed-push)) before building an `InboxSnapshot` via
|
|
`inbox.list_pending()` and sending a sealed `inbox_update` to every Authorized
|
|
client. Each approval
|
|
carries a humanised `summary` (from `Tool::describe(Short)`, computed in
|
|
`Inbox::list_pending`) for the card/notification plus the raw `arguments`
|
|
(untruncated) for the detail dialog — so the user sees the full `execute_cmd`
|
|
command, not a truncated label. Each clarification carries its
|
|
`suggested_answers`. Each elicitation carries **only** its prompt metadata
|
|
(`server_name`, `message`, `field_name`, `sensitive`, `is_confirmation`) — never
|
|
a value; the value is supplied by the device in `elicitation_response.content`.
|
|
- **Clients → Inbox:** inbound `message` is checked (`from` ∈ Authorized,
|
|
nonce direction + counter > `recv_counter`), opened, and dispatched by `kind`:
|
|
`approval_response` → `inbox.approve/reject`, `clarification_response` →
|
|
`inbox.answer`, `elicitation_response` → `inbox.resolve_elicitation` (its
|
|
`content` may be a secret — never logged/persisted in clear), `hello` → persist
|
|
`device_info`, `inbox_request` → send a **targeted** `inbox_update` back to
|
|
`from` only (see below), `logout` → revoke.
|
|
After any response the Inbox is re-snapshotted. `request_id` is mapped
|
|
`string ↔ i64` (non-parsing ids are dropped). Inbox ops are idempotent by
|
|
`request_id`.
|
|
- **Reconnect snapshot (`inbox_request`):** the relay does **not** notify the
|
|
agent when a client reconnects, so the client sends `inbox_request` on the
|
|
**live channel** (`Message.live=true`) after every `auth_ok` (e.g. when the app
|
|
is opened from a push). The agent replies with an `inbox_update` sealed to the
|
|
requester only — not a broadcast — so other devices are not needlessly
|
|
re-aligned. A pull of stale state is useless, so the live channel is correct:
|
|
if the agent is offline, the client gets `PeerOffline` immediately instead of
|
|
waiting. Side-effect-free and idempotent (by `request_id`). See
|
|
`data/ios-app/v2/relay-protocol.md` §3.1.
|
|
|
|
---
|
|
|
|
## HTTP reverse proxy (`http-local-proxy`)
|
|
|
|
So a remote device can reach Skald's web UI **without** a VPN/Tailscale or an open
|
|
port, the plugin reuses the relay **pipe** (relayed E2E byte-stream, see
|
|
[relay/pipe.md](../relay/pipe.md)) as a reverse proxy to the local HTTP server.
|
|
|
|
`proxy.rs` subscribes to `RelayClient::incoming_pipes()` and, for each invite with
|
|
`stream_type == "http-local-proxy"`, accepts the pipe and splices it byte-for-byte
|
|
to a **fresh** `TcpStream` to `127.0.0.1:<web_port>` (`PluginContext::web_port`).
|
|
Per pipe it `split`s the connection into independent send/receive halves and runs
|
|
each direction in its own task (full-duplex, so neither blocks the other;
|
|
`PipeSender::send` is backpressured by the pipe's ~10 MiB send buffer, and
|
|
`recv`/`read` are cancel-safe — see [relay/pipe.md §6.1](../relay/pipe.md#61-full-duplex--client-side-backpressure)).
|
|
When either direction ends it cancels a shared token so the other unwinds. Invites
|
|
of other `stream_type`s are **ignored** (not rejected) since `incoming_pipes` is a
|
|
broadcast shared with possible future consumers.
|
|
|
|
The native app side (later) opens one pipe per outbound connection and points a
|
|
WebView at it; because the tunnel is a transparent TCP splice, HTTP/1.1 keep-alive,
|
|
parallel connections, and the chat WebSocket upgrade all work unchanged.
|
|
|
|
**Security.**
|
|
|
|
- The destination is **pinned** to `127.0.0.1:<web_port>` — the client cannot pick
|
|
host/port, so this is not an open localhost proxy (no SSRF to other local services).
|
|
- Access is gated by the relay's pipe auth (`pipe.md §3.1`): only the namespace
|
|
agent or an **authorized** client can establish a pipe.
|
|
- It exposes the full local web UI remotely — that is the intent; pair/authorize
|
|
devices accordingly.
|
|
|
|
**Relay tuning** (env, `pipe.md §3.3`): a browser opens several connections, so
|
|
`RELAY_PIPE_MAX_PER_NS` (default 8) may need raising; an idle chat-WS pipe can be
|
|
reaped at `RELAY_PIPE_IDLE_TIMEOUT_SECS` (120 s) — the frontend auto-reconnects.
|
|
|
|
Teardown: `proxy_one` takes a child of the plugin cancel token, so plugin stop
|
|
closes active tunnels; `stop_inner` also `shutdown()`s the relay client.
|
|
|
|
---
|
|
|
|
## Delayed push
|
|
|
|
A phone push is only valuable when the user is *away* from the computer. When
|
|
they're at the chat, every approval/clarification would otherwise fire an
|
|
instant — and pointless — notification, since they answer on the computer within
|
|
seconds. `DelayedNotifier` (`notifier.rs`) debounces this between the bus events
|
|
and `broadcast_inbox()`. (Elicitations are not chat-inline, so they are exempt —
|
|
see below.)
|
|
|
|
- **`*_requested`** arms a timer (`notify_delay_secs`, default 20s) keyed by
|
|
`(kind, request_id)` — approvals, clarifications, and elicitations use
|
|
independent id counters, so the kind is part of the key. If the timer elapses unresolved, the
|
|
key is marked *notified* and the Inbox is pushed (`broadcast_inbox`, `live=false`
|
|
→ store-and-forward / offline push).
|
|
- **Elicitations are the exception**: they live *only* in the Inbox (never
|
|
inline in the chat, unlike approvals/clarifications), so there is no
|
|
computer-side answer to debounce against. They skip the timer and are pushed
|
|
**immediately**, regardless of `notify_delay_secs`.
|
|
- **`*_resolved`** before the timer fires ⇒ the timer is cancelled and **nothing
|
|
is sent**. If the push already went out, the resolution is broadcast so the
|
|
phone clears the item. (Untracked ids fall back to a broadcast for snapshot
|
|
freshness.)
|
|
|
|
This only affects the **phone**: the desktop/web approval UI runs over the
|
|
per-session WebSocket (`ApprovalRequired`/`AgentQuestion`) and is never delayed.
|
|
Phone-driven responses (`apply_client_payload`) still `broadcast_inbox()`
|
|
immediately; the subsequent `*_resolved` bus event is handled idempotently. Armed
|
|
timers are cancelled on plugin stop (`cancel_all`). Set `notify_delay_secs: 0`
|
|
for the previous instant-push behaviour.
|
|
|
|
---
|
|
|
|
## LLM tools (plugin.md §11)
|
|
|
|
| Tool | Effect | Approval |
|
|
|---|---|---|
|
|
| `mobile_start_pairing(ttl?)` | Open the pairing window, return the QR URL | **Gated** (a default `require` rule is seeded, like `execute_cmd`/`restart`) |
|
|
| `mobile_list_devices()` | List devices (state, platform, device_info, last_seen) | read-only |
|
|
| `mobile_revoke_device(pubkey)` | Revoke a device by hex ed25519 pubkey | `Config` category |
|
|
|
|
These tools are not contributed through the `Plugin` trait (which has no
|
|
`tools()` method). They are registered in `Tools::build` (`src/core/skald/bundles.rs`):
|
|
the plugin is fetched via `get_plugin_typed::<MobileConnectorPlugin>()`, cast to
|
|
`Arc<dyn RelayAgent>`, and bound into the tools via
|
|
`plugin_mobile_connector::mobile_tools(agent)` → `ToolRegistry::register_arc`.
|
|
|
|
`mobile_start_pairing`'s approval gate is the default rule seeded in
|
|
`ApprovalManager::seed_defaults` (`src/core/approval/mod.rs`): opening a window
|
|
emits a secret (the QR) into chat, so it must be a deliberate human action, not
|
|
LLM-triggerable via prompt injection.
|
|
|
|
---
|
|
|
|
## HTTP endpoint
|
|
|
|
`GET /api/plugin/mobile-connector/pairingqrcode?code=<random>` — runtime PNG of
|
|
the QR (or placeholder), behind Skald's normal auth. Mounted by `WebFrontend`
|
|
via `Plugin::http_router()` (the router closes over the live `RelayState`). The
|
|
`code` is a non-enumerable capability; a URL leaked into `chat_history`
|
|
self-revokes once the window closes.
|