phase 7.0: capability-only WebSocket — devices untethered from any one AI

new endpoint WS /ws/expose. devices register WITHOUT a publisher's
api_key — hub mints a dx_... device key on first registration, stores
in new sqlite table `exposures(exposure_id, name, manifest_json,
device_key_hash, first_seen, last_seen)`. re-registration with the
same device_key restores the same exposure_id (persistence).

new SDK function zhub.expose(name, capabilities, public=True) mirrors
connect()'s shape but is AI-untethered. handlers receive invoke-request
envelopes the same way connect() handlers do.

new HTTP surfaces:
  GET /exposures
    public-flagged exposures only, no auth, returns name + caps +
    uptime for discovery.
  POST /exposures/<exposure_id>/invoke
    auth: any registered publisher's zk_ bearer key. body:
    {capability, args}. args validated against the exposure's
    declared json schema (same plumbing as /v1/invoke). same envelope
    unwrap as the connection-side invoke path.

zhub now has three peer roles: publisher (the AI), connection (paired
client), exposure (untethered device). exposures are the "USB
peripherals" of the hub — register once, available to every AI on it.

tests: 11 new (5 persistence + 6 e2e via real WS+httpx). 141/141
pytest now.

spec at docs/superpowers/specs/2026-05-10-zhub-phase-7.0-capability-only-ws-design.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Zawwarsami16

CLAUDE.md

@@ -92,8 +92,9 @@ Tests: `pytest -v`. The e2e tests spin up the hub in-process and run the full pu
 - **Phase 5.2** ✅ — Entity expansion: added `## install`, `## up`, `## paths` sections to `entity.md`. Header notes the file ships with the package so an AI installing zhub can read it locally before any hub is running.
 - **Phase 5.3** ✅ — `AnthropicAdapter` brain (5th adapter). Anthropic Messages API has its own SSE shape (`event:`/`data:` pairs, `content_block_delta` with `text_delta`); adapter normalizes to `ChatChunk` like the others. Registered in REGISTRY after Cerebras.
 - **Phase 6.0** ✅ — Production-readiness pack: structured access logs at `zhub.access` logger (one line per request: status + method + path + latency_ms + ai_name when applicable); per-AI latency tracking surfaced in `/metrics` (`request_count`, `total_latency_ms`, `max_latency_ms`, `avg_latency_ms`); `python -m zhub up --tunnel-name <name>` for cloudflared *named* tunnels (stable URL across restarts); README gets a mermaid arch diagram; new `docs/DEPLOY.md` walkthrough for a $5 VPS deployment with systemd unit files for hub + named tunnel.
+- **Phase 7.0** ✅ — Capability-only WebSocket (`/ws/expose`). Devices register tools without pairing to any specific AI; hub mints `dx_` device key + `ex_` exposure id, persists across restarts. `GET /exposures` (public discovery), `POST /exposures/<id>/invoke` (any registered publisher's `zk_` key authorizes; same JSON-Schema validation as `/v1/invoke`). New SDK function `zhub.expose(name, capabilities, public=True)` mirrors `connect()` shape but is AI-untethered. The "USB peripherals for AIs on the hub" primitive — register once, available to all.
 
-**Next (not started):** true tool_call delta streaming through SSE (4.2b), multi-tier API keys, capability-only WS connections (a "tool provider" usable by any AI on the hub, not tied to one publisher), MCP resources/prompts surface.
+**Next (not started):** true tool_call delta streaming through SSE (4.2b), multi-tier API keys, MCP resources/prompts surface, more brain adapters (Cohere/Mistral/Together/Bedrock/Vertex).
 
 ## 6. File layout (what's where)
 

tests/test_exposures.py

@@ -0,0 +1,236 @@
+"""Phase 7.0 — capability-only exposures end-to-end.
+
+A device registers via /ws/expose without being paired to any AI.
+Any registered publisher's bearer key can invoke its capabilities.
+"""
+
+import asyncio
+import socket
+import threading
+import time
+
+import pytest
+
+try:
+    import fastapi  # noqa
+    import uvicorn  # noqa
+    import httpx  # noqa
+    DEPS_AVAILABLE = True
+except ImportError:
+    DEPS_AVAILABLE = False
+
+if DEPS_AVAILABLE:
+    from zhub.server import create_app
+from zhub import publish, expose
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture
+def hub(tmp_path):
+    if not DEPS_AVAILABLE:
+        pytest.skip("fastapi/uvicorn/httpx not installed")
+    port = _free_port()
+    db_path = str(tmp_path / "exp.db")
+    app = create_app(db_path=db_path)
+
+    def run():
+        config = uvicorn.Config(app, host="127.0.0.1", port=port,
+                                log_level="warning")
+        asyncio.run(uvicorn.Server(config).serve())
+
+    threading.Thread(target=run, daemon=True).start()
+    for _ in range(30):
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.1):
+                break
+        except OSError:
+            time.sleep(0.1)
+    yield port
+
+
+@pytest.mark.asyncio
+async def test_register_exposure_returns_id_and_key(hub):
+    """expose() registers the device and the hub returns an exposure_id
+    + dx_ device key."""
+    exp = expose(
+        name="weather-sensor",
+        capabilities={
+            "weather_lookup": (
+                {"type": "object",
+                 "properties": {"city": {"type": "string"}},
+                 "required": ["city"]},
+                lambda args: {"temp": 22, "city": args["city"]},
+            ),
+        },
+        hub_url=f"ws://127.0.0.1:{hub}",
+        public=True,
+    )
+    for _ in range(50):
+        if exp.exposure_id and exp.device_key:
+            break
+        await asyncio.sleep(0.1)
+    assert exp.exposure_id.startswith("ex_"), f"got {exp.exposure_id!r}"
+    assert exp.device_key.startswith("dx_"), f"got {exp.device_key!r}"
+
+
+@pytest.mark.asyncio
+async def test_get_exposures_lists_public_only(hub):
+    e_pub = expose(
+        name="weather-public",
+        capabilities={"weather_lookup": ({"type": "object"}, lambda a: {})},
+        hub_url=f"ws://127.0.0.1:{hub}",
+        public=True,
+    )
+    e_priv = expose(
+        name="secret-camera",
+        capabilities={"take_photo": ({"type": "object"}, lambda a: {})},
+        hub_url=f"ws://127.0.0.1:{hub}",
+        public=False,
+    )
+    for _ in range(50):
+        if e_pub.exposure_id and e_priv.exposure_id:
+            break
+        await asyncio.sleep(0.1)
+
+    async with httpx.AsyncClient(timeout=5.0) as c:
+        listing = (await c.get(f"http://127.0.0.1:{hub}/exposures")).json()
+
+    names = {e["name"] for e in listing}
+    assert "weather-public" in names
+    assert "secret-camera" not in names
+
+
+@pytest.mark.asyncio
+async def test_invoke_exposure_via_publisher_key(hub):
+    """A registered publisher's zk_ key authorizes invoking any exposure."""
+    captured: dict = {}
+    e = expose(
+        name="weather",
+        capabilities={
+            "weather_lookup": (
+                {"type": "object", "required": ["city"],
+                 "properties": {"city": {"type": "string"}}},
+                lambda a: {"city": a["city"], "temp": 18,
+                           "_captured": captured.update(a) or True},
+            ),
+        },
+        hub_url=f"ws://127.0.0.1:{hub}",
+        public=True,
+    )
+    for _ in range(50):
+        if e.exposure_id:
+            break
+        await asyncio.sleep(0.1)
+
+    pub = publish(
+        name="some-ai",
+        description="any AI",
+        chat_handler=lambda m, o: "ok",
+        hub_url=f"ws://127.0.0.1:{hub}",
+    )
+    for _ in range(50):
+        if pub.api_key:
+            break
+        await asyncio.sleep(0.1)
+
+    async with httpx.AsyncClient(timeout=5.0) as c:
+        resp = await c.post(
+            f"http://127.0.0.1:{hub}/exposures/{e.exposure_id}/invoke",
+            json={"capability": "weather_lookup", "args": {"city": "Mississauga"}},
+            headers={"Authorization": f"Bearer {pub.api_key}"},
+        )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["ok"] is True
+    assert body["result"]["city"] == "Mississauga"
+    assert body["result"]["temp"] == 18
+    assert captured == {"city": "Mississauga"}
+
+
+@pytest.mark.asyncio
+async def test_invoke_rejects_without_publisher_key(hub):
+    e = expose(
+        name="x",
+        capabilities={"do_x": ({"type": "object"}, lambda a: {"ok": True})},
+        hub_url=f"ws://127.0.0.1:{hub}",
+        public=True,
+    )
+    for _ in range(50):
+        if e.exposure_id:
+            break
+        await asyncio.sleep(0.1)
+
+    async with httpx.AsyncClient(timeout=5.0) as c:
+        # No bearer
+        r = await c.post(
+            f"http://127.0.0.1:{hub}/exposures/{e.exposure_id}/invoke",
+            json={"capability": "do_x", "args": {}},
+        )
+    assert r.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_invoke_404_for_unknown_exposure(hub):
+    pub = publish(
+        name="auth-source",
+        description="x",
+        chat_handler=lambda m, o: "ok",
+        hub_url=f"ws://127.0.0.1:{hub}",
+    )
+    for _ in range(50):
+        if pub.api_key:
+            break
+        await asyncio.sleep(0.1)
+
+    async with httpx.AsyncClient(timeout=5.0) as c:
+        r = await c.post(
+            f"http://127.0.0.1:{hub}/exposures/ex_nope/invoke",
+            json={"capability": "x", "args": {}},
+            headers={"Authorization": f"Bearer {pub.api_key}"},
+        )
+    assert r.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_invoke_validates_args_against_schema(hub):
+    e = expose(
+        name="strict",
+        capabilities={
+            "strict_op": (
+                {"type": "object", "required": ["needed"],
+                 "properties": {"needed": {"type": "string"}}},
+                lambda a: {"got": a},
+            ),
+        },
+        hub_url=f"ws://127.0.0.1:{hub}",
+        public=True,
+    )
+    for _ in range(50):
+        if e.exposure_id:
+            break
+        await asyncio.sleep(0.1)
+
+    pub = publish(
+        name="caller",
+        description="x",
+        chat_handler=lambda m, o: "ok",
+        hub_url=f"ws://127.0.0.1:{hub}",
+    )
+    for _ in range(50):
+        if pub.api_key:
+            break
+        await asyncio.sleep(0.1)
+
+    async with httpx.AsyncClient(timeout=5.0) as c:
+        r = await c.post(
+            f"http://127.0.0.1:{hub}/exposures/{e.exposure_id}/invoke",
+            json={"capability": "strict_op", "args": {}},
+            headers={"Authorization": f"Bearer {pub.api_key}"},
+        )
+    assert r.status_code == 400
+    assert "needed" in r.text.lower()

tests/test_exposures_persistence.py

@@ -0,0 +1,56 @@
+"""Phase 7.0 — SQLite storage for capability-only exposures."""
+
+import pytest
+
+from zhub.persistence import Storage, hash_key
+
+
+@pytest.fixture
+def store(tmp_path):
+    return Storage(tmp_path / "test.db")
+
+
+def test_add_exposure_returns_id_and_persists(store):
+    eid = store.add_exposure(
+        name="weather-sensor",
+        manifest={"capabilities": [{"name": "weather_lookup"}], "public": True},
+        device_key_hash=hash_key("dx_secret"),
+    )
+    assert eid.startswith("ex_")
+    rows = store.all_exposures()
+    assert len(rows) == 1
+    e = rows[0]
+    assert e["exposure_id"] == eid
+    assert e["name"] == "weather-sensor"
+    assert e["manifest"]["public"] is True
+    assert e["device_key_hash"] == hash_key("dx_secret")
+
+
+def test_lookup_exposure_by_id(store):
+    eid = store.add_exposure("x", {}, hash_key("dx_a"))
+    found = store.lookup_exposure(eid)
+    assert found is not None
+    assert found["exposure_id"] == eid
+
+
+def test_lookup_exposure_by_device_key(store):
+    eid = store.add_exposure("x", {}, hash_key("dx_unique"))
+    found = store.lookup_exposure_by_key_hash(hash_key("dx_unique"))
+    assert found is not None
+    assert found["exposure_id"] == eid
+
+
+def test_remove_exposure(store):
+    eid = store.add_exposure("x", {}, hash_key("dx_y"))
+    store.remove_exposure(eid)
+    assert store.lookup_exposure(eid) is None
+    assert store.all_exposures() == []
+
+
+def test_exposures_persist_across_reopen(tmp_path):
+    db = tmp_path / "p.db"
+    s1 = Storage(db)
+    eid = s1.add_exposure("x", {}, hash_key("dx_z"))
+    s1.close()
+    s2 = Storage(db)
+    assert s2.lookup_exposure(eid) is not None

zhub/__init__.py

@@ -41,7 +41,9 @@
     conn.run_forever()
 """
 
-from .client import publish, connect, ZhubPublication, ZhubConnection
+from .client import (
+    publish, connect, expose, ZhubPublication, ZhubConnection, ZhubExposure,
+)
 from .manifest import Manifest, Capability
 from .errors import ZhubError, AuthError, ConnectionError as ZhubConnectionError
 
@@ -58,8 +60,10 @@
 __all__ = [
     "publish",
     "connect",
+    "expose",
     "ZhubPublication",
     "ZhubConnection",
+    "ZhubExposure",
     "Manifest",
     "Capability",
     "ZhubError",