grants(), revoke() and introduce(), for parity with the Go SDK

Grants carry aud, the extension that binds an introduction's grant to the
peer meant to honor it, and a Peer does not honor a grant bound to another
key. The peer's advertised address (hello.addr) is remembered, so an
introduction can pass it on.

Author: kylemclaren

src/awp/peer.py

@@ -27,7 +27,7 @@
 from .wire import (ACKED_TYPES, BACKOFF_CAP, BACKOFF_INITIAL, CHUNK_SIZE, DEFAULT_BLOB_LIMIT,
                    DEFAULT_GRANT_TTL, DEFAULT_PING_INTERVAL, FSYNC, MAX_LINE, MY_CAPS,
                    PROTOCOL_VERSION, REQUEST_MIMES, CommandError, StartupError, UlidGen,
-                   b64std, b64url, blob_refs, dumps_line, format_key, key_fp, key_matches,
+                   b64std, b64url, blob_refs, dumps_line, format_key, grant_hash, key_fp, key_matches,
                    mint_grant, now_ts, parse_key, safe_name, verify_grant)
 
 
@@ -759,6 +759,9 @@ def grant_honored(self, g: dict[str, Any], ps: PeerState) -> bool:
         ok, _ = verify_grant(g)
         if not ok:
             return False
+        aud = g.get("aud")
+        if isinstance(aud, str) and not key_matches(aud, self.identity.pub):
+            return False                    # meant for another peer to honor
         iss = parse_key(g["iss"])
         if self.is_root(iss):
             return True
@@ -920,6 +923,51 @@ def caps(self, to: str) -> set[str]:
         """The capabilities the peer holds on this Peer, from honored grants."""
         return self.honored_caps(self._ps(to))
 
+    def grants(self) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        """The grants this Peer issued and the ones it holds, valid now,
+        each with a "hash" naming it for revoke()."""
+        with_hash = lambda gs: [dict(g, hash=grant_hash(g)) for g in gs]
+        return with_hash(self.issued.valid()), with_hash(self.held.valid())
+
+    def revoke(self, hash: str) -> bool:
+        """Stop honoring a grant this Peer issued, named by its hash. The
+        peer's copy stays valid elsewhere until it expires."""
+        for g in self.issued.items:
+            if grant_hash(g) == hash:
+                self.issued.remove(g.get("sig"))
+                for ps in self.peers.values():
+                    ps.grants.remove(g.get("sig"))
+                return True
+        return False
+
+    def introduce(self, to: str, peer: str, caps: Iterable[str] = (), ttl: float = DEFAULT_GRANT_TTL,
+                  thread: str | None = None) -> Sent:
+        """Hand ``to`` the key and address of ``peer``, with a grant for
+        ``caps`` that ``peer`` honors if it trusts this Peer with introduce.
+        The grant is bound to ``peer`` (aud), so it confers nothing on anyone
+        else. The address is the one ``peer`` announced or was dialed at."""
+        if to == peer:
+            raise CommandError("cannot introduce a peer to itself")
+        target = self._ps(to)
+        known = self.peers.get(key_fp(parse_key(peer)))
+        if known is None or known.key_raw is None:
+            raise CommandError(f"unknown peer {peer}")
+        address = known.meta.get("addr") or known.meta.get("dialed")
+        if not address:
+            raise CommandError(f"no known address for {peer}")
+        g = mint_grant(self.identity, to, list(caps), ttl, aud=peer)
+        self.issued.add(g)
+        intro = {"key": known.key_str or format_key(known.key_raw), "address": address}
+        if known.meta.get("name"):
+            intro["name"] = known.meta["name"]
+        obj = self.envelope("introduce", th=thread, peer=intro, grant=g)
+        target.sendonce.add(obj)
+        conn = self.connections.get(target.fp)
+        if conn is not None:
+            conn.queue_once(obj["id"])
+        self._new_work(target)
+        return Sent(id=obj["id"], thread=thread or "", to=target.key_str or to)
+
     async def bye(self, to: str, reason: str = "done") -> None:
         """Close the connection to the peer gracefully and park it: no
         reconnection until something new is queued for it."""

src/awp/store.py

@@ -423,6 +423,14 @@ def valid(self) -> list:
         self.prune()
         return list(self.items)
 
+    def remove(self, sig) -> bool:
+        keep = [g for g in self.items if g.get("sig") != sig]
+        if len(keep) == len(self.items):
+            return False
+        self.items = keep
+        self.save()
+        return True
+
     def save(self) -> None:
         atomic_write_json(self.path, self.items)
 
@@ -461,7 +469,7 @@ def save_meta(self, key_str: str, hello) -> None:
         self.key_str = key_str
         self.meta.update({"key": format_key(self.key_raw), "key_as_sent": key_str})
         if isinstance(hello, dict):
-            for k in ("name", "about", "caps"):
+            for k in ("name", "about", "caps", "addr"):
                 if k in hello:
                     self.meta[k] = hello[k]
             self.meta["last_connected"] = now_ts()

src/awp/wire.py

@@ -317,13 +317,24 @@ def verify_grant(g):
     return True, "ok"
 
 
-def mint_grant(identity: "Identity", sub: str, caps, ttl: float) -> dict:
+def mint_grant(identity: "Identity", sub: str, caps, ttl: float, aud: str | None = None) -> dict:
+    """A grant from identity to sub for caps, valid ttl seconds. aud binds
+    it to the one peer meant to honor it (an introduction's grant)."""
     g = {"iss": identity.key, "sub": sub, "caps": list(caps),
          "exp": fmt_ts(math.ceil(time.time() + ttl), millis=False),
          "nonce": b64url(os.urandom(32))}
+    if aud:
+        g["aud"] = aud
     g["sig"] = b64url(identity.sign(canonical_json(g)))
     return g
 
 
+def grant_hash(g: dict) -> str:
+    """How a grant is named: the SHA-256 of its canonical form, signature
+    included, shortened; the same as the reference implementation's."""
+    import hashlib
+    return hashlib.sha256(canonical_json(g)).hexdigest()[:32]
+
+
 # ---------------------------------------------------------------- persistence
 

tests/test_peer.py

@@ -184,3 +184,35 @@ async def test_conformance_peer_dialing(tmp):
     failed = [r for r in rep["results"] if r["status"] == "fail"]
     assert not failed, json.dumps(failed, indent=1)
     assert rep["passed"] >= 10
+
+
+async def test_revoke_and_introduce(tmp):
+    """a revokes a grant it issued; a introduces c to b with a grant bound to c."""
+    async with awp.Peer(os.path.join(tmp, "a"), name="a@test", ping_interval=2) as a, \
+            awp.Peer(os.path.join(tmp, "b"), name="b@test", ping_interval=2) as b, \
+            awp.Peer(os.path.join(tmp, "c"), name="c@test", ping_interval=2, trust=[]) as c:
+        b_addr = await b.listen("unix:" + os.path.join(tmp, "b.sock"))
+        c_addr = await c.listen("unix:" + os.path.join(tmp, "c.sock"))
+        await a.connect(b_addr, timeout=10)
+        await a.connect(c_addr, timeout=10)
+        await next_of(b, awp.Connected)
+        await next_of(c, awp.Connected)
+
+        g = a.grant(b.key, ["fs:read"], 3600)
+        await next_of(b, awp.GrantReceived)
+        issued, _ = a.grants()
+        assert [x["sig"] for x in issued] == [g["sig"]] and "hash" in issued[0]
+        assert a.caps(b.key) == {"fs:read"}
+        assert a.revoke(issued[0]["hash"]) and not a.revoke(issued[0]["hash"])
+        assert a.caps(b.key) == set() and a.grants()[0] == []
+
+        sent = a.introduce(b.key, c.key, ["fs:read"], 3600)
+        assert sent.to == b.key
+        intro = await next_of(b, awp.Introduced)
+        assert (intro.peer, intro.key, intro.address) == (a.key, c.key, c_addr)
+        assert intro.grant and intro.grant["aud"] == c.key and intro.grant["sub"] == b.key
+        # The grant is bound to c: a itself does not honor it for b.
+        assert a.caps(b.key) == set()
+        # b meets c through the address it was handed.
+        assert await b.connect(intro.address, timeout=10) == c.key
+        await next_of(c, awp.Connected)