willows-grove 0.9.0__py3-none-any.whl

bridge/__init__.py

@@ -0,0 +1 @@
+# bridge — Grove ↔ Matrix Application Service bridge

bridge/__main__.py

@@ -0,0 +1,112 @@
+"""
+Grove ↔ Matrix bridge.
+
+Tokens are never passed as CLI args — they live in an env file or environment
+variables so they stay out of shell history and process listings.
+
+Usage:
+  # Generate tokens once:
+  python3 -c "import secrets; print(secrets.token_hex(32))"   # as_token
+  python3 -c "import secrets; print(secrets.token_hex(32))"   # hs_token
+
+  # Write to ~/.willow/bridge/tokens.env (chmod 600):
+  GROVE_AS_TOKEN=<as_token>
+  GROVE_HS_TOKEN=<hs_token>
+
+  # Run:
+  python3 -m bridge \\
+    --homeserver https://matrix.example.com \\
+    --hs-name    example.com \\
+    --env-file   ~/.willow/bridge/tokens.env
+
+  # Or via environment directly (e.g. systemd EnvironmentFile):
+  GROVE_AS_TOKEN=... GROVE_HS_TOKEN=... python3 -m bridge ...
+
+Then copy bridge/registration.yaml to your Synapse config dir and add it to
+homeserver.yaml under `app_service_config_files`.
+"""
+
+import argparse
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+from .app import GroveMatrixBridge
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(name)-22s  %(levelname)s  %(message)s",
+)
+
+
+def _load_env_file(path: Path) -> None:
+    """Parse a simple KEY=VALUE env file into os.environ. Ignores comments and blanks."""
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip())
+
+
+def _require_env(name: str) -> str:
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise SystemExit(
+            f"Error: {name} is not set.\n"
+            f"Add it to your --env-file or set it as an environment variable."
+        )
+    return value
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        description="Grove ↔ Matrix bridge",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--homeserver", required=True, help="Matrix homeserver URL")
+    p.add_argument("--hs-name",    required=True, help="Homeserver name (e.g. example.com)")
+    p.add_argument("--env-file",   default=None,  help="Path to KEY=VALUE env file for tokens")
+    p.add_argument("--grove-port", type=int, default=8551, help="u2u listen port (default 8551)")
+    p.add_argument("--as-port",    type=int, default=8560, help="AS HTTP server port (default 8560)")
+    p.add_argument("--data-dir",   default="~/.willow/bridge", help="State directory")
+    args = p.parse_args()
+
+    if args.env_file:
+        env_path = Path(args.env_file).expanduser()
+        if not env_path.exists():
+            raise SystemExit(f"Error: env file not found: {env_path}")
+        _load_env_file(env_path)
+
+    as_token = _require_env("GROVE_AS_TOKEN")
+    hs_token = _require_env("GROVE_HS_TOKEN")
+
+    data = Path(args.data_dir).expanduser()
+    data.mkdir(parents=True, exist_ok=True)
+
+    bridge = GroveMatrixBridge(
+        homeserver    = args.homeserver,
+        hs_name       = args.hs_name,
+        as_token      = as_token,
+        hs_token      = hs_token,
+        grove_port    = args.grove_port,
+        as_port       = args.as_port,
+        identity_path = data / "identity.json",
+        store_path    = data / "bridge.db",
+    )
+
+    print("Grove ↔ Matrix bridge starting")
+    print(f"  homeserver  → {args.homeserver}")
+    print(f"  AS server   → http://0.0.0.0:{args.as_port}")
+    print(f"  u2u port    → {args.grove_port}")
+    print(f"  data dir    → {data}")
+    print()
+
+    asyncio.run(bridge.run())
+
+
+if __name__ == "__main__":
+    main()

bridge/app.py

@@ -0,0 +1,311 @@
+# bridge/app.py — Grove ↔ Matrix bridge coordinator
+"""
+Flow summary
+============
+
+Matrix user → Grove user
+  1. Matrix user invites @grove_<hex_addr>:<hs> to a DM room
+  2. ASServer receives m.room.member/invite
+  3. Bridge sends u2u KNOCK to Grove addr
+  4. Grove user sees KNOCK in their TUI, approves
+  5. Grove user sends a NOTE back to bridge (implicit approval signal)
+  6. Bridge marks mapping active, delivers NOTE as Matrix message
+  7. Subsequent Matrix messages → u2u NOTEs, and vice versa
+
+Grove user → Matrix user
+  1. Grove user KNOCKs the bridge at bridge_addr
+  2. Bridge receives KNOCK, creates Matrix DM room, invites the target Matrix user
+     (target must be pre-configured or resolved from a directory — out of scope for now)
+  Currently: Grove-initiated flow requires the Matrix user to initiate first.
+"""
+
+import asyncio
+import logging
+import socket
+from pathlib import Path
+
+from aiohttp import web
+
+from u2u import dispatcher
+from u2u.consent import ConsentGate
+from u2u.contacts import ContactStore
+from u2u.identity import Identity
+from u2u.listener import U2UListener
+from u2u.packets import PacketType
+from u2u.sender import send_packet
+
+from .matrix import ASServer, MatrixClient
+from .store import BridgeStore
+
+log = logging.getLogger("bridge.app")
+
+
+def _addr_to_localpart(addr: str) -> str:
+    """grove addr → hex string safe for Matrix localpart."""
+    return addr.encode().hex()
+
+
+def _localpart_to_addr(localpart: str) -> str:
+    """Reverse of _addr_to_localpart. Raises ValueError on bad input."""
+    return bytes.fromhex(localpart).decode()
+
+
+def _puppet_id(grove_addr: str, hs_name: str) -> str:
+    return f"@grove_{_addr_to_localpart(grove_addr)}:{hs_name}"
+
+
+def _resolve_local_ip() -> str:
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            return s.getsockname()[0]
+    except OSError:
+        return "localhost"
+
+
+class GroveMatrixBridge:
+    def __init__(
+        self,
+        homeserver: str,
+        hs_name: str,
+        as_token: str,
+        hs_token: str,
+        grove_port: int,
+        as_port: int,
+        identity_path: Path,
+        store_path: Path,
+    ):
+        self._hs_name    = hs_name
+        self._grove_port = grove_port
+        self._as_port    = as_port
+
+        self.identity = Identity.load_or_generate(identity_path)
+        self.store    = BridgeStore(store_path)
+
+        local_ip = _resolve_local_ip()
+        self._bridge_addr = f"grove_bridge@{local_ip}:{grove_port}"
+
+        contacts_path = identity_path.parent / "grove_bridge_contacts.json"
+        self.contacts = ContactStore(contacts_path)
+
+        self._bot_id = f"@grove_bridge:{hs_name}"
+        self.matrix  = MatrixClient(homeserver, as_token, self._bot_id)
+        self._as_srv = ASServer(hs_token, self._on_matrix_event)
+
+        log.info("bridge addr: %s", self._bridge_addr)
+
+    async def run(self) -> None:
+        await self.matrix.start()
+        try:
+            await asyncio.gather(
+                self._run_grove_listener(),
+                self._run_as_server(),
+            )
+        finally:
+            await self.matrix.close()
+
+    # ── Grove listener ───────────────────────────────────────────────
+
+    async def _run_grove_listener(self) -> None:
+        gate = ConsentGate(self.contacts)
+
+        def _on_note(packet: dict) -> None:
+            h         = packet["header"]
+            pl        = packet.get("payload", {})
+            from_addr = h.get("from", "")
+            body      = pl.get("body", "")
+            if h.get("_denied"):
+                log.debug("denied NOTE from %s", from_addr)
+                return
+            asyncio.get_running_loop().create_task(
+                self._grove_note(from_addr, body)
+            )
+
+        def _on_knock(packet: dict) -> None:
+            h         = packet["header"]
+            pl        = packet.get("payload", {})
+            from_addr = h.get("from", "")
+            pubkey    = pl.get("public_key", "")
+            asyncio.get_running_loop().create_task(
+                self._grove_knock(from_addr, pubkey)
+            )
+
+        dispatcher.register(PacketType.NOTE,  _on_note)
+        dispatcher.register(PacketType.KNOCK, _on_knock)
+
+        listener = U2UListener(
+            host="0.0.0.0", port=self._grove_port,
+            identity=self.identity, consent=gate,
+        )
+        async with listener.serve():
+            await asyncio.Event().wait()
+
+    # See INVARIANTS.md §5 — this is the re-KNOCK admission the section
+    # names: the caller has already verified the packet signature, but
+    # admission itself must never silently rotate a trusted key.
+    def _admit_contact(self, from_addr: str, pubkey: str) -> bool:
+        """Admit `from_addr` with `pubkey`, never silently rotating a key.
+
+        A first admission creates the contact. A repeat presentation of the
+        SAME key is a no-op. A DIFFERENT key is refused and logged: rotating a
+        peer's trusted key is an operator decision, and doing it from an
+        inbound packet is exactly how a re-KNOCK became a full trust reset.
+        """
+        if not pubkey:
+            return False
+        existing = self.contacts.get(from_addr)
+        if existing is None:
+            self.contacts.add(from_addr, pubkey)
+            log.info("admitted Grove contact %s", from_addr)
+            return True
+        if existing.public_key_hex == pubkey:
+            return True
+        log.warning(
+            "REFUSED key rotation for %s — inbound key %s… does not match the "
+            "stored key; existing key, blocked state and consent flags kept",
+            from_addr, pubkey[:16],
+        )
+        return False
+
+    async def _grove_note(self, from_addr: str, body: str) -> None:
+        """Grove NOTE → Matrix message. First NOTE from a pending addr = approval."""
+        mapping = self.store.get_by_grove_addr(from_addr)
+        if not mapping:
+            log.warning("NOTE from unmapped Grove addr %s — dropped", from_addr)
+            return
+
+        if mapping["state"] == "pending_knock":
+            # First NOTE = implicit KNOCK approval. Admit them to contacts and activate.
+            pending = self.store.get_pending_knock(from_addr)
+            if pending and pending["public_key"]:
+                self._admit_contact(from_addr, pending["public_key"])
+                self.store.clear_pending_knock(from_addr)
+            self.store.activate(from_addr)
+            await self.matrix.send_notice(
+                mapping["matrix_room"],
+                f"Grove user {from_addr} accepted the connection.",
+            )
+
+        puppet = _puppet_id(from_addr, self._hs_name)
+        await self.matrix.ensure_virtual_user(puppet)
+        await self.matrix.send_message(mapping["matrix_room"], body, as_user=puppet)
+        log.info("Grove→Matrix  %s → %s", from_addr, mapping["matrix_room"])
+
+    async def _grove_knock(self, from_addr: str, pubkey: str) -> None:
+        """
+        Grove KNOCK → bridge queues it. Matrix user must have already invited
+        the puppet (creating a mapping) for this to activate. Otherwise just
+        store the pubkey for when the invite arrives.
+        """
+        mapping = self.store.get_by_grove_addr(from_addr)
+        if mapping and mapping["state"] == "active":
+            # Re-knock from a known contact. This used to "update key
+            # silently", which reset blocked and every consent flag along with
+            # it. A re-KNOCK now confirms the existing key or is refused.
+            self._admit_contact(from_addr, pubkey)
+            return
+
+        self.store.set_pending_knock(from_addr, pubkey)
+        log.info("queued KNOCK from %s", from_addr)
+
+    # ── Matrix AS server ───────────────────────────────────────────
+
+    async def _run_as_server(self) -> None:
+        app   = self._as_srv.build_app()
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, "0.0.0.0", self._as_port)
+        await site.start()
+        log.info("AS server on port %d", self._as_port)
+        await asyncio.Event().wait()
+
+    async def _on_matrix_event(self, event: dict) -> None:
+        etype = event.get("type")
+        if etype == "m.room.member":
+            await self._mx_member(event)
+        elif etype == "m.room.message":
+            await self._mx_message(event)
+
+    async def _mx_member(self, event: dict) -> None:
+        """Matrix invite to a grove_* puppet → send KNOCK to that Grove addr."""
+        if event.get("content", {}).get("membership") != "invite":
+            return
+
+        state_key = event.get("state_key", "")   # the invited user
+        room_id   = event.get("room_id", "")
+        inviter   = event.get("sender", "")
+
+        if not state_key.startswith("@grove_"):
+            return
+
+        localpart = state_key.split(":")[0].lstrip("@")[len("grove_"):]
+
+        # Bridge bot itself invited → just join
+        if localpart == "bridge":
+            await self.matrix.join_room(room_id, as_user=self._bot_id)
+            return
+
+        try:
+            grove_addr = _localpart_to_addr(localpart)
+        except (ValueError, UnicodeDecodeError):
+            log.warning("bad grove addr in puppet %s", state_key)
+            return
+
+        # Persist mapping (pending until Grove user sends their first NOTE)
+        self.store.upsert(grove_addr, room_id, inviter, state="pending_knock")
+
+        # Accept the invite on behalf of the puppet
+        puppet = state_key
+        await self.matrix.ensure_virtual_user(puppet)
+        await self.matrix.join_room(room_id, as_user=puppet)
+
+        # Send u2u KNOCK to the Grove user
+        ok = await send_packet(
+            PacketType.KNOCK,
+            self._bridge_addr,
+            grove_addr,
+            {"public_key": self.identity.public_key_hex},
+            self.identity,
+        )
+
+        notice = (
+            f"Knocked Grove user at {grove_addr}. Waiting for them to approve."
+            if ok else
+            f"Could not reach Grove user at {grove_addr} — are they online?"
+        )
+        await self.matrix.send_notice(room_id, notice)
+        log.info("Matrix→Grove KNOCK: %s → %s (ok=%s)", inviter, grove_addr, ok)
+
+    async def _mx_message(self, event: dict) -> None:
+        """Matrix message → u2u NOTE to Grove user."""
+        sender  = event.get("sender", "")
+        room_id = event.get("room_id", "")
+        body    = event.get("content", {}).get("body", "")
+
+        # Ignore messages from our own puppets to avoid loops
+        if sender.startswith("@grove_"):
+            return
+
+        mapping = self.store.get_by_matrix_room(room_id)
+        if not mapping:
+            return
+
+        grove_addr = mapping["grove_addr"]
+
+        if mapping["state"] == "pending_knock":
+            await self.matrix.send_notice(
+                room_id,
+                "Waiting for Grove user to approve the connection. Message not sent.",
+            )
+            return
+
+        ok = await send_packet(
+            PacketType.NOTE,
+            self._bridge_addr,
+            grove_addr,
+            {"subject": "", "body": body},
+            self.identity,
+        )
+        if not ok:
+            await self.matrix.send_notice(room_id, "Grove user appears offline — message not delivered.")
+        log.info("Matrix→Grove NOTE: %s → %s (ok=%s)", sender, grove_addr, ok)

bridge/matrix.py

@@ -0,0 +1,109 @@
+# bridge/matrix.py — Matrix CS API client + Application Service HTTP server
+import logging
+import time
+from aiohttp import web, ClientSession, ClientTimeout
+
+log = logging.getLogger("bridge.matrix")
+
+_TIMEOUT = ClientTimeout(total=15)
+
+
+class MatrixClient:
+    """Minimal Matrix Client-Server API wrapper for a bridge bot."""
+
+    def __init__(self, homeserver: str, as_token: str, bot_user_id: str):
+        self._hs        = homeserver.rstrip("/")
+        self._token     = as_token
+        self._bot       = bot_user_id
+        self._session: ClientSession | None = None
+
+    async def start(self) -> None:
+        self._session = ClientSession(
+            headers={"Authorization": f"Bearer {self._token}"},
+            timeout=_TIMEOUT,
+        )
+
+    async def close(self) -> None:
+        if self._session:
+            await self._session.close()
+
+    def _cs(self, path: str) -> str:
+        return f"{self._hs}/_matrix/client/v3{path}"
+
+    async def ensure_virtual_user(self, user_id: str) -> None:
+        """Register virtual user if not already registered. Idempotent."""
+        localpart = user_id.split(":")[0].lstrip("@")
+        async with self._session.post(
+            f"{self._hs}/_matrix/client/v3/register",
+            json={"type": "m.login.application_service", "username": localpart},
+        ) as r:
+            # 200 = registered, 400 M_USER_IN_USE = already exists — both are fine
+            if r.status not in (200, 400):
+                log.warning("register %s → %s", user_id, r.status)
+
+    async def join_room(self, room_id: str, as_user: str) -> bool:
+        async with self._session.post(
+            self._cs(f"/join/{room_id}"),
+            params={"user_id": as_user},
+            json={},
+        ) as r:
+            ok = r.status == 200
+            if not ok:
+                log.warning("join_room %s as %s → %s", room_id, as_user, r.status)
+            return ok
+
+    async def send_message(self, room_id: str, body: str, as_user: str) -> bool:
+        txn_id = str(int(time.monotonic() * 1_000_000))
+        async with self._session.put(
+            self._cs(f"/rooms/{room_id}/send/m.room.message/{txn_id}"),
+            params={"user_id": as_user},
+            json={"msgtype": "m.text", "body": body},
+        ) as r:
+            ok = r.status == 200
+            if not ok:
+                log.warning("send_message %s → %s", room_id, r.status)
+            return ok
+
+    async def send_notice(self, room_id: str, body: str) -> bool:
+        """Send a bridge status notice as the bot itself."""
+        return await self.send_message(room_id, f"[bridge] {body}", as_user=self._bot)
+
+
+class ASServer:
+    """
+    Receives transaction events POSTed by the homeserver.
+    Passes each event to on_event(event: dict) coroutine.
+    """
+
+    _SEEN_MAX = 2048
+
+    def __init__(self, hs_token: str, on_event):
+        self._hs_token  = hs_token
+        self._on_event  = on_event
+        self._seen: dict[str, None] = {}  # insertion-ordered dict as bounded LRU
+
+    def build_app(self) -> web.Application:
+        app = web.Application()
+        app.router.add_put("/transactions/{txn_id}", self._handle_txn)
+        return app
+
+    async def _handle_txn(self, request: web.Request) -> web.Response:
+        token = request.headers.get("Authorization", "").removeprefix("Bearer ")
+        if token != self._hs_token:
+            return web.Response(status=403)
+
+        txn_id = request.match_info["txn_id"]
+        if txn_id in self._seen:
+            return web.json_response({})
+        self._seen[txn_id] = None
+        if len(self._seen) > self._SEEN_MAX:
+            self._seen.pop(next(iter(self._seen)))
+
+        body = await request.json()
+        for event in body.get("events", []):
+            try:
+                await self._on_event(event)
+            except Exception as e:
+                log.error("event handler error: %s", e)
+
+        return web.json_response({})

bridge/registration.yaml

@@ -0,0 +1,24 @@
+# Grove ↔ Matrix Application Service registration
+# Copy this file to your Synapse config directory, then add to homeserver.yaml:
+#
+#   app_service_config_files:
+#     - /path/to/grove_bridge_registration.yaml
+#
+# Generate fresh tokens with: python3 -c "import secrets; print(secrets.token_hex(32))"
+
+id: grove-bridge
+url: "http://localhost:8560"       # where Synapse POSTs events (your bridge's AS port)
+
+as_token: "REPLACE_WITH_AS_TOKEN"  # = GROVE_AS_TOKEN in your env file
+hs_token: "REPLACE_WITH_HS_TOKEN"  # = GROVE_HS_TOKEN in your env file
+
+sender_localpart: grove_bridge     # the bridge bot's Matrix localpart
+
+namespaces:
+  users:
+    - exclusive: true
+      regex: '@grove_.*'           # bridge owns all @grove_* virtual users
+  rooms:  []
+  aliases: []
+
+rate_limited: false

bridge/store.py

@@ -0,0 +1,69 @@
+# bridge/store.py — SQLite mapping: grove addr ↔ Matrix room ↔ Matrix user
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+
+class BridgeStore:
+    def __init__(self, path: Path):
+        self._db = sqlite3.connect(str(path), check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        self._db.executescript("""
+            CREATE TABLE IF NOT EXISTS mappings (
+                grove_addr   TEXT PRIMARY KEY,
+                matrix_room  TEXT NOT NULL,
+                matrix_user  TEXT NOT NULL,
+                state        TEXT NOT NULL DEFAULT 'pending_knock'
+            );
+            CREATE TABLE IF NOT EXISTS pending_knocks (
+                grove_addr  TEXT PRIMARY KEY,
+                public_key  TEXT NOT NULL,
+                created_at  REAL DEFAULT (unixepoch('now'))
+            );
+        """)
+
+    def get_by_grove_addr(self, addr: str) -> Optional[sqlite3.Row]:
+        return self._db.execute(
+            "SELECT * FROM mappings WHERE grove_addr = ?", (addr,)
+        ).fetchone()
+
+    def get_by_matrix_room(self, room_id: str) -> Optional[sqlite3.Row]:
+        return self._db.execute(
+            "SELECT * FROM mappings WHERE matrix_room = ?", (room_id,)
+        ).fetchone()
+
+    def upsert(self, grove_addr: str, matrix_room: str, matrix_user: str,
+               state: str = "pending_knock") -> None:
+        self._db.execute("""
+            INSERT INTO mappings (grove_addr, matrix_room, matrix_user, state)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT (grove_addr) DO UPDATE SET
+                matrix_room = excluded.matrix_room,
+                matrix_user = excluded.matrix_user,
+                state       = excluded.state
+        """, (grove_addr, matrix_room, matrix_user, state))
+        self._db.commit()
+
+    def activate(self, grove_addr: str) -> None:
+        self._db.execute(
+            "UPDATE mappings SET state = 'active' WHERE grove_addr = ?", (grove_addr,)
+        )
+        self._db.commit()
+
+    def set_pending_knock(self, grove_addr: str, public_key: str) -> None:
+        self._db.execute("""
+            INSERT OR REPLACE INTO pending_knocks (grove_addr, public_key)
+            VALUES (?, ?)
+        """, (grove_addr, public_key))
+        self._db.commit()
+
+    def get_pending_knock(self, grove_addr: str) -> Optional[sqlite3.Row]:
+        return self._db.execute(
+            "SELECT * FROM pending_knocks WHERE grove_addr = ?", (grove_addr,)
+        ).fetchone()
+
+    def clear_pending_knock(self, grove_addr: str) -> None:
+        self._db.execute(
+            "DELETE FROM pending_knocks WHERE grove_addr = ?", (grove_addr,)
+        )
+        self._db.commit()

grove/__init__.py

@@ -0,0 +1 @@
+"""Grove dashboard package — theme and vitals for Textual shell."""