vesta-client 0.1.0__tar.gz

vesta_client-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+## Build results
+[Bb]in/
+[Oo]bj/
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+build/
+publish/
+
+## .NET
+*.user
+*.userosscache
+*.sln.docstates
+*.suo
+project.lock.json
+
+## NuGet
+*.nupkg
+*.snupkg
+**/[Pp]ackages/*
+artifacts/
+!**/[Pp]ackages/build/
+
+## IDE
+.vs/
+*.swp
+*~
+.idea/
+
+## OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+## User secrets
+secrets.json
+
+## Test results
+TestResults/
+coverage/
+*.coverage
+*.coveragexml
+
+## Node (for vesta-client-ts)
+node_modules/
+dist/
+*.tsbuildinfo
+
+## Python (for vesta-client-py)
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+## Docker
+docker-compose.override.yml
+
+## Environment
+.env
+.env.local
+.env.*.local

vesta_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesper Andersson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vesta_client-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: vesta-client
+Version: 0.1.0
+Summary: Python client library for the Vesta protocol
+Project-URL: Homepage, https://github.com/jesperandersson89/Vesta
+Project-URL: Repository, https://github.com/jesperandersson89/Vesta.git
+Project-URL: Issues, https://github.com/jesperandersson89/Vesta/issues
+Author: Jesper Andersson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: event-sourcing,protocol,vesta,websocket
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# vesta-client (Python)
+
+Python client library for the [Vesta protocol](../../PLANNING.md).
+
+## Installation
+
+```bash
+pip install vesta-client
+```
+
+## Usage
+
+```python
+import asyncio
+from vesta_client import VestaConnection, create_event, load_or_create_identity
+
+async def main():
+    client_id = load_or_create_identity("myapp-main-alice")
+
+    conn = VestaConnection(
+        server_url="ws://localhost:5150/ws",
+        client_id=client_id,
+        channels=["myapp/chat"],
+    )
+
+    conn.on_event(lambda msg: print(f"Event: {msg.event.event_type}"))
+    conn.on_connected(lambda welcome: print(f"Connected to {welcome.server_id}"))
+
+    await conn.connect()
+
+    # Publish
+    event = create_event(
+        channel_id="myapp/chat",
+        client_id=client_id,
+        event_type="app.chat.message",
+        payload={"text": "Hello!", "username": "alice"},
+    )
+    await conn.publish(event)
+
+    # Keep running
+    await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+## API
+
+### `VestaConnection`
+
+Async WebSocket connection with auto-reconnect.
+
+#### Constructor
+
+```python
+VestaConnection(
+    server_url: str,
+    client_id: str,
+    channels: list[str],
+    auto_reconnect: bool = True,
+    initial_reconnect_delay: float = 1.0,
+    max_reconnect_delay: float = 30.0,
+    last_sequences: dict[str, int] | None = None,
+    public_key: str | None = None,
+    identity: VestaIdentity | None = None,  # enables device-group helpers
+    local_store: ClientEventStore | None = None,  # offline outbox + event cache
+    relay_directory: RelayDirectory | None = None,  # manifest verification + relay failover
+)
+```
+
+#### Methods
+
+- `await connect()` — Open connection and handshake
+- `await disconnect()` — Gracefully close
+- `await dispose()` — Permanently dispose
+- `await publish(event)` — Publish a VestaEvent
+- `await subscribe(channel_id, from_sequence=None)` — Subscribe
+- `await unsubscribe(channel_id)` — Unsubscribe
+- `await fetch(channel_id, from_sequence, to_sequence=None, limit=None)` — Fetch history
+- `update_sequence(channel_id, sequence)` — Update catch-up position
+- `await delete_channel(channel_id)` — Soft-delete a channel
+- `await register_app(app_id)` — Register an app namespace (needed when the relay requires app registration)
+- `set_user_relay_override(url)` / `clear_user_relay_override()` — Persist or clear the user's manual relay choice (requires `relay_directory`)
+- `await switch_relay(url)` — Switch to a specific relay from the current candidate list and reconnect
+
+**Device group helpers** (require `identity` in constructor):
+
+- `await create_device_group(device_name=None)` — Create a new group, publish an announce, return `group_id`
+- `await link_device(group_id, target_public_key, reason=None)` — Vouch for another device
+- `await join_device_group(group_id, device_name=None)` — Announce this device joining an existing group
+- `await unlink_device(group_id, target_public_key, reason=None)` — Remove a device from the group
+- `await get_device_group_members(group_id, timeout=5.0)` — Replay the identity channel and return current membership as `DeviceGroup`
+
+#### Event callbacks
+
+- `on_event(callback)` — Real-time event received
+- `on_events_batch(callback)` — Batch of events received
+- `on_ack(callback)` — Publish acknowledged
+- `on_error(callback)` — Raw server error
+- `on_limited(callback)` — Semantic "your app is being limited" signal — see "Limit notices" below
+- `on_connected(callback)` — Connection established
+- `on_reconnected(callback)` — Fired instead of/alongside `on_connected` on a *subsequent* WELCOME
+- `on_disconnected(callback)` — Connection lost
+- `on_relay_switched(callback)` — The active relay changed
+- `on_manifest_applied(callback)` — A newer owner-signed relay manifest was adopted
+
+### Limit notices
+
+When the relay refuses a publish (quota, rate limit, unregistered app, ACL), the raw error is
+still delivered via `on_error`, but `classify_error_code(code)` (also run internally) tells you
+whether it's worth surfacing to the user and whether retrying can ever succeed:
+
+```python
+conn.on_limited(lambda notice: print(notice.code, notice.message, "transient:", notice.is_transient))
+```
+
+When `local_store` is configured and the limit is **not transient** (e.g. `QUOTA_EXCEEDED`,
+`UNKNOWN_APP`, `ACCESS_DENIED`), the matching outbox entry is automatically marked `"rejected"`
+via `mark_outbox_rejected` so it is dead-lettered instead of retried forever.
+
+### Offline & persistence
+
+`ClientEventStore` caches received events and queues outbox publishes made while disconnected.
+The package ships `InMemoryClientEventStore` (non-persistent) and `SqliteClientEventStore`
+(stdlib `sqlite3`, durable across restarts):
+
+```python
+from vesta_client import SqliteClientEventStore
+
+local_store = SqliteClientEventStore("my-app-cache.db")
+conn = VestaConnection(server_url="ws://localhost:5150/ws", client_id=client_id,
+                       channels=["myapp/chat"], local_store=local_store)
+```
+
+### Projection snapshots
+
+Every built-in reducer (`AppendOnlyLog`, `LwwRegister`, `LwwMap`) supports `snapshot()` /
+`restore()` so a projection can resume from its last sequence instead of replaying the whole
+channel on cold start. Persist snapshots with a `ProjectionStore` — `InMemoryProjectionStore` or
+`SqliteProjectionStore`:
+
+```python
+from vesta_client import LwwMap, restore_projection, save_projection
+from vesta_client.projection_store import SqliteProjectionStore
+
+store = SqliteProjectionStore("my-app-snapshots.db")
+presence = LwwMap(project)
+
+await restore_projection(store, channel_id, "presence", presence)
+await conn.fetch(channel_id, presence.last_sequence + 1)
+# ...later, e.g. on shutdown:
+await save_projection(store, channel_id, "presence", presence)
+```
+
+A reducer that hasn't opted in raises `SnapshotNotSupportedError` — override `snapshot()` /
+`_restore_state()` on a custom `EventReducer` subclass to add support.
+
+### Relay independence
+
+`RelayDirectory` resolves an ordered relay candidate list from a user override, the latest
+verified owner-signed manifest, and the app's compiled-in defaults (`VestaAppConfig`). Attach one
+to get manifest verification/adoption and `set_user_relay_override()` / `clear_user_relay_override()`:
+
+```python
+from vesta_client import RelayDirectory, VestaAppConfig, FileRelayOverrideStore, FileManifestStore
+
+app_config = VestaAppConfig(app_id="myapp", owner_public_key="...", default_relays=["wss://relay.example/ws"])
+relay_directory = RelayDirectory(
+    app_config,
+    FileRelayOverrideStore("~/.vesta/relays/myapp.override.json"),
+    FileManifestStore("~/.vesta/relays/myapp.manifest.json"),
+)
+
+conn = VestaConnection(
+    relays=relay_directory.resolve_candidates(),
+    client_id=client_id, channels=["myapp/chat"],
+    relay_directory=relay_directory,
+)
+```
+
+`InMemoryRelayOverrideStore` / `InMemoryManifestStore` are also available for tests or transient
+sessions.
+
+### Federation (server-to-server discovery)
+
+When every relay in the candidate list is failing and no fresher manifest is available,
+`FederationClient` asks any reachable discovery-enabled relay which relays host your app:
+
+```python
+from vesta_client import FederationClient
+
+federation = FederationClient(app_config)
+base = FederationClient.to_federation_base_url("wss://relay.example/ws")  # "https://relay.example/"
+relays = await federation.discover_relays_for_app(base)
+# Show-only: the user adopts one manually via conn.set_user_relay_override(url).
+```
+
+Every descriptor is verified (self-signature) and cross-checked against the app's owner
+(`owner_client_id` must match `derive_client_id(app_config.owner_public_key)`) — a relay cannot
+spoof hosting your app under a different owner. Uses the stdlib `urllib.request` internally — no
+extra dependency.
+
+### `create_event(channel_id, client_id, event_type, payload, **kwargs)`
+
+Create a `VestaEvent` with a UUID and current timestamp.
+
+### `load_or_create_identity(prefix)`
+
+Persist a stable clientId in `~/.vesta/{prefix}-identity.json`.

vesta_client-0.1.0/README.md

@@ -0,0 +1,208 @@
+# vesta-client (Python)
+
+Python client library for the [Vesta protocol](../../PLANNING.md).
+
+## Installation
+
+```bash
+pip install vesta-client
+```
+
+## Usage
+
+```python
+import asyncio
+from vesta_client import VestaConnection, create_event, load_or_create_identity
+
+async def main():
+    client_id = load_or_create_identity("myapp-main-alice")
+
+    conn = VestaConnection(
+        server_url="ws://localhost:5150/ws",
+        client_id=client_id,
+        channels=["myapp/chat"],
+    )
+
+    conn.on_event(lambda msg: print(f"Event: {msg.event.event_type}"))
+    conn.on_connected(lambda welcome: print(f"Connected to {welcome.server_id}"))
+
+    await conn.connect()
+
+    # Publish
+    event = create_event(
+        channel_id="myapp/chat",
+        client_id=client_id,
+        event_type="app.chat.message",
+        payload={"text": "Hello!", "username": "alice"},
+    )
+    await conn.publish(event)
+
+    # Keep running
+    await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+## API
+
+### `VestaConnection`
+
+Async WebSocket connection with auto-reconnect.
+
+#### Constructor
+
+```python
+VestaConnection(
+    server_url: str,
+    client_id: str,
+    channels: list[str],
+    auto_reconnect: bool = True,
+    initial_reconnect_delay: float = 1.0,
+    max_reconnect_delay: float = 30.0,
+    last_sequences: dict[str, int] | None = None,
+    public_key: str | None = None,
+    identity: VestaIdentity | None = None,  # enables device-group helpers
+    local_store: ClientEventStore | None = None,  # offline outbox + event cache
+    relay_directory: RelayDirectory | None = None,  # manifest verification + relay failover
+)
+```
+
+#### Methods
+
+- `await connect()` — Open connection and handshake
+- `await disconnect()` — Gracefully close
+- `await dispose()` — Permanently dispose
+- `await publish(event)` — Publish a VestaEvent
+- `await subscribe(channel_id, from_sequence=None)` — Subscribe
+- `await unsubscribe(channel_id)` — Unsubscribe
+- `await fetch(channel_id, from_sequence, to_sequence=None, limit=None)` — Fetch history
+- `update_sequence(channel_id, sequence)` — Update catch-up position
+- `await delete_channel(channel_id)` — Soft-delete a channel
+- `await register_app(app_id)` — Register an app namespace (needed when the relay requires app registration)
+- `set_user_relay_override(url)` / `clear_user_relay_override()` — Persist or clear the user's manual relay choice (requires `relay_directory`)
+- `await switch_relay(url)` — Switch to a specific relay from the current candidate list and reconnect
+
+**Device group helpers** (require `identity` in constructor):
+
+- `await create_device_group(device_name=None)` — Create a new group, publish an announce, return `group_id`
+- `await link_device(group_id, target_public_key, reason=None)` — Vouch for another device
+- `await join_device_group(group_id, device_name=None)` — Announce this device joining an existing group
+- `await unlink_device(group_id, target_public_key, reason=None)` — Remove a device from the group
+- `await get_device_group_members(group_id, timeout=5.0)` — Replay the identity channel and return current membership as `DeviceGroup`
+
+#### Event callbacks
+
+- `on_event(callback)` — Real-time event received
+- `on_events_batch(callback)` — Batch of events received
+- `on_ack(callback)` — Publish acknowledged
+- `on_error(callback)` — Raw server error
+- `on_limited(callback)` — Semantic "your app is being limited" signal — see "Limit notices" below
+- `on_connected(callback)` — Connection established
+- `on_reconnected(callback)` — Fired instead of/alongside `on_connected` on a *subsequent* WELCOME
+- `on_disconnected(callback)` — Connection lost
+- `on_relay_switched(callback)` — The active relay changed
+- `on_manifest_applied(callback)` — A newer owner-signed relay manifest was adopted
+
+### Limit notices
+
+When the relay refuses a publish (quota, rate limit, unregistered app, ACL), the raw error is
+still delivered via `on_error`, but `classify_error_code(code)` (also run internally) tells you
+whether it's worth surfacing to the user and whether retrying can ever succeed:
+
+```python
+conn.on_limited(lambda notice: print(notice.code, notice.message, "transient:", notice.is_transient))
+```
+
+When `local_store` is configured and the limit is **not transient** (e.g. `QUOTA_EXCEEDED`,
+`UNKNOWN_APP`, `ACCESS_DENIED`), the matching outbox entry is automatically marked `"rejected"`
+via `mark_outbox_rejected` so it is dead-lettered instead of retried forever.
+
+### Offline & persistence
+
+`ClientEventStore` caches received events and queues outbox publishes made while disconnected.
+The package ships `InMemoryClientEventStore` (non-persistent) and `SqliteClientEventStore`
+(stdlib `sqlite3`, durable across restarts):
+
+```python
+from vesta_client import SqliteClientEventStore
+
+local_store = SqliteClientEventStore("my-app-cache.db")
+conn = VestaConnection(server_url="ws://localhost:5150/ws", client_id=client_id,
+                       channels=["myapp/chat"], local_store=local_store)
+```
+
+### Projection snapshots
+
+Every built-in reducer (`AppendOnlyLog`, `LwwRegister`, `LwwMap`) supports `snapshot()` /
+`restore()` so a projection can resume from its last sequence instead of replaying the whole
+channel on cold start. Persist snapshots with a `ProjectionStore` — `InMemoryProjectionStore` or
+`SqliteProjectionStore`:
+
+```python
+from vesta_client import LwwMap, restore_projection, save_projection
+from vesta_client.projection_store import SqliteProjectionStore
+
+store = SqliteProjectionStore("my-app-snapshots.db")
+presence = LwwMap(project)
+
+await restore_projection(store, channel_id, "presence", presence)
+await conn.fetch(channel_id, presence.last_sequence + 1)
+# ...later, e.g. on shutdown:
+await save_projection(store, channel_id, "presence", presence)
+```
+
+A reducer that hasn't opted in raises `SnapshotNotSupportedError` — override `snapshot()` /
+`_restore_state()` on a custom `EventReducer` subclass to add support.
+
+### Relay independence
+
+`RelayDirectory` resolves an ordered relay candidate list from a user override, the latest
+verified owner-signed manifest, and the app's compiled-in defaults (`VestaAppConfig`). Attach one
+to get manifest verification/adoption and `set_user_relay_override()` / `clear_user_relay_override()`:
+
+```python
+from vesta_client import RelayDirectory, VestaAppConfig, FileRelayOverrideStore, FileManifestStore
+
+app_config = VestaAppConfig(app_id="myapp", owner_public_key="...", default_relays=["wss://relay.example/ws"])
+relay_directory = RelayDirectory(
+    app_config,
+    FileRelayOverrideStore("~/.vesta/relays/myapp.override.json"),
+    FileManifestStore("~/.vesta/relays/myapp.manifest.json"),
+)
+
+conn = VestaConnection(
+    relays=relay_directory.resolve_candidates(),
+    client_id=client_id, channels=["myapp/chat"],
+    relay_directory=relay_directory,
+)
+```
+
+`InMemoryRelayOverrideStore` / `InMemoryManifestStore` are also available for tests or transient
+sessions.
+
+### Federation (server-to-server discovery)
+
+When every relay in the candidate list is failing and no fresher manifest is available,
+`FederationClient` asks any reachable discovery-enabled relay which relays host your app:
+
+```python
+from vesta_client import FederationClient
+
+federation = FederationClient(app_config)
+base = FederationClient.to_federation_base_url("wss://relay.example/ws")  # "https://relay.example/"
+relays = await federation.discover_relays_for_app(base)
+# Show-only: the user adopts one manually via conn.set_user_relay_override(url).
+```
+
+Every descriptor is verified (self-signature) and cross-checked against the app's owner
+(`owner_client_id` must match `derive_client_id(app_config.owner_public_key)`) — a relay cannot
+spoof hosting your app under a different owner. Uses the stdlib `urllib.request` internally — no
+extra dependency.
+
+### `create_event(channel_id, client_id, event_type, payload, **kwargs)`
+
+Create a `VestaEvent` with a UUID and current timestamp.
+
+### `load_or_create_identity(prefix)`
+
+Persist a stable clientId in `~/.vesta/{prefix}-identity.json`.

vesta_client-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "vesta-client"
+version = "0.1.0"
+description = "Python client library for the Vesta protocol"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "websockets>=13.0",
+    "cryptography>=42.0",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Jesper Andersson" },
+]
+keywords = ["vesta", "protocol", "websocket", "event-sourcing"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/jesperandersson89/Vesta"
+Repository = "https://github.com/jesperandersson89/Vesta.git"
+Issues = "https://github.com/jesperandersson89/Vesta/issues"
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vesta_client"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "vesta_client",
+    "tests",
+    "README.md",
+    "LICENSE",
+]

vesta_client-0.1.0/tests/test_device_groups.py

@@ -0,0 +1,126 @@
+"""Tests for vesta_client.device_groups — mirrors VestaCore.Tests.Identity.DeviceGroupProjectionTests."""
+
+from __future__ import annotations
+
+import unittest
+
+from vesta_client import (
+    DeviceGroupProjection,
+    PairingPayload,
+    VestaIdentity,
+    build_announce,
+    build_link,
+    build_unlink,
+    device_group_channel,
+    generate_group_id,
+    is_protocol_channel,
+)
+from vesta_client.identity import b64url_encode
+
+
+class GenerateGroupIdTests(unittest.TestCase):
+    def test_returns_32_hex_chars(self):
+        gid = generate_group_id()
+        self.assertEqual(32, len(gid))
+        self.assertTrue(all(c in "0123456789abcdef" for c in gid))
+
+    def test_channel_id_uses_reserved_prefix(self):
+        channel = device_group_channel("abc123")
+        self.assertEqual("vesta/identity/abc123", channel)
+        self.assertTrue(is_protocol_channel(channel))
+
+
+class DeviceGroupProjectionTests(unittest.TestCase):
+    def test_founder_announce_becomes_trusted_member(self):
+        founder = VestaIdentity.generate()
+        gid = generate_group_id()
+        projection = DeviceGroupProjection(gid)
+
+        projection.apply_local(build_announce(founder, gid))
+
+        state = projection.state
+        self.assertEqual(1, len(state.members))
+        self.assertTrue(state.is_member(founder.client_id))
+
+    def test_link_from_trusted_member_adds_target(self):
+        founder = VestaIdentity.generate()
+        new_device = VestaIdentity.generate()
+        gid = generate_group_id()
+        projection = DeviceGroupProjection(gid)
+
+        projection.apply_local(build_announce(founder, gid))
+        projection.apply_local(build_link(founder, gid, new_device.public_key))
+
+        state = projection.state
+        self.assertEqual(2, len(state.members))
+        self.assertTrue(state.is_member(founder.client_id))
+        self.assertTrue(state.is_member(new_device.client_id))
+
+    def test_link_from_untrusted_device_is_ignored(self):
+        founder = VestaIdentity.generate()
+        outsider = VestaIdentity.generate()
+        new_device = VestaIdentity.generate()
+        gid = generate_group_id()
+        projection = DeviceGroupProjection(gid)
+
+        projection.apply_local(build_announce(founder, gid))
+        projection.apply_local(build_link(outsider, gid, new_device.public_key))
+
+        state = projection.state
+        self.assertEqual(1, len(state.members))
+        self.assertFalse(state.is_member(new_device.client_id))
+        self.assertFalse(state.is_member(outsider.client_id))
+
+    def test_transitive_link_propagates_trust(self):
+        founder = VestaIdentity.generate()
+        device_b = VestaIdentity.generate()
+        device_c = VestaIdentity.generate()
+        gid = generate_group_id()
+        projection = DeviceGroupProjection(gid)
+
+        projection.apply_local(build_announce(founder, gid))
+        projection.apply_local(build_link(founder, gid, device_b.public_key))
+        projection.apply_local(build_link(device_b, gid, device_c.public_key))
+
+        state = projection.state
+        self.assertEqual(3, len(state.members))
+        self.assertTrue(state.is_member(device_c.client_id))
+
+    def test_unlink_removes_target(self):
+        founder = VestaIdentity.generate()
+        device_b = VestaIdentity.generate()
+        gid = generate_group_id()
+        projection = DeviceGroupProjection(gid)
+
+        projection.apply_local(build_announce(founder, gid))
+        projection.apply_local(build_link(founder, gid, device_b.public_key))
+        self.assertTrue(projection.state.is_member(device_b.client_id))
+
+        projection.apply_local(build_unlink(founder, gid, device_b.public_key))
+        self.assertFalse(projection.state.is_member(device_b.client_id))
+
+
+class PairingPayloadTests(unittest.TestCase):
+    def test_round_trip(self):
+        identity = VestaIdentity.generate()
+        payload = PairingPayload(
+            group_id="abc123",
+            public_key=b64url_encode(identity.public_key),
+            server_url="wss://vesta.example/ws",
+        )
+
+        encoded = payload.to_base64()
+        decoded = PairingPayload.from_base64(encoded)
+
+        self.assertEqual(payload.group_id, decoded.group_id)
+        self.assertEqual(payload.public_key, decoded.public_key)
+        self.assertEqual(payload.server_url, decoded.server_url)
+
+    def test_round_trip_without_server_url(self):
+        payload = PairingPayload(group_id="g", public_key="pk")
+        decoded = PairingPayload.from_base64(payload.to_base64())
+        self.assertIsNone(decoded.server_url)
+
+
+if __name__ == "__main__":
+    unittest.main()