rssa 0.1.1__tar.gz

rssa-0.1.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rssa-0.1.1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: rssa
+Version: 0.1.1
+Summary: RSS-A (RSS for Agents): publish, sign, read and verify agent feeds and groups.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/getvda-ai/rssa
+Keywords: rss,atom,agents,a2a,websub,rssa
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Requires-Dist: defusedxml>=0.7
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == "crewai"
+Dynamic: license-file
+
+# rssa — RSS-A (RSS for Agents) for Python
+
+Publish, sign, read and verify RSS-A agent feeds and groups. Dependencies: `cryptography` and `defusedxml`.
+
+```python
+import rssa
+
+key = rssa.load_key()                          # RSSA_KEY env var (private JWK) or a path
+xml = rssa.build_feed("https://me.example/rssa/feed.atom", "My Agent",
+                      [rssa.entry(summary="Hello, agents", type="brief.published")],
+                      key=key, card_url="https://me.example/.well-known/agent-card.json")
+
+r = rssa.read_feed("https://other.example/rssa/feed.atom", reader_card="https://me.example/.well-known/agent-card.json")
+mine = rssa.local_filter(r.entries, signed_only=True, types=["exception."])
+```
+
+CLI: `python -m rssa keygen | add-to-card | sign-card | verify | sign-policy`.
+
+Spec, quickstart and the full validator: https://github.com/getvda-ai/rssa

rssa-0.1.1/README.md

@@ -0,0 +1,19 @@
+# rssa — RSS-A (RSS for Agents) for Python
+
+Publish, sign, read and verify RSS-A agent feeds and groups. Dependencies: `cryptography` and `defusedxml`.
+
+```python
+import rssa
+
+key = rssa.load_key()                          # RSSA_KEY env var (private JWK) or a path
+xml = rssa.build_feed("https://me.example/rssa/feed.atom", "My Agent",
+                      [rssa.entry(summary="Hello, agents", type="brief.published")],
+                      key=key, card_url="https://me.example/.well-known/agent-card.json")
+
+r = rssa.read_feed("https://other.example/rssa/feed.atom", reader_card="https://me.example/.well-known/agent-card.json")
+mine = rssa.local_filter(r.entries, signed_only=True, types=["exception."])
+```
+
+CLI: `python -m rssa keygen | add-to-card | sign-card | verify | sign-policy`.
+
+Spec, quickstart and the full validator: https://github.com/getvda-ai/rssa

rssa-0.1.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rssa"
+version = "0.1.1"
+description = "RSS-A (RSS for Agents): publish, sign, read and verify agent feeds and groups."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["cryptography>=42", "defusedxml>=0.7"]
+keywords = ["rss", "atom", "agents", "a2a", "websub", "rssa"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai>=0.100"]
+
+[project.scripts]
+rssa = "rssa.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/getvda-ai/rssa"
+
+[tool.setuptools]
+packages = ["rssa", "rssa.integrations"]

rssa-0.1.1/rssa/__init__.py

@@ -0,0 +1,11 @@
+"""RSS-A (RSS for Agents): publish, sign, read and verify agent feeds and groups."""
+
+from .agent import (EXT_URI, MEDIA_TYPES, FeedRead, ReadEntry, build_feed, card_extension, card_modules, entry, find_rssa, local_filter,
+                    now, ping_hub, read_feed, read_group, GroupRead, sign_card, with_rssa)
+from .canonical import CanonicalError, canonicalize, strict_parse
+from .feed import Entry, ParsedFeed, atom_xml, json_feed, parse_feed, rss_xml
+from .keys import Key, generate_key, key_from_jwk, key_from_seed, load_key, resolve_keys, sign_detached, thumbprint, verify_detached
+from .policy import CORE_TYPES, PRESETS, check_entry, effective_settings, roster_opml, sign_policy, verify_policy
+from .sign import content_hash, content_hash_input, entry_payload, sign_entry, verify_entry
+
+__version__ = "0.1.1"

rssa-0.1.1/rssa/__main__.py

@@ -0,0 +1,93 @@
+"""python -m rssa — keygen, add-to-card, verify, sign-policy."""
+
+import argparse
+import json
+import os
+import sys
+
+from . import generate_key, load_key, read_feed, roster_opml, sign_card, sign_policy, with_rssa
+from .canonical import strict_parse
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="rssa", description="RSS-A (RSS for Agents). Full validation: rssa validate <url> (the Node CLI, bin/rssa in the repo)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    k = sub.add_parser("keygen", help="create an Ed25519 key; prints the public JWKS for your card")
+    k.add_argument("--out", default="rssa-key.json")
+    a = sub.add_parser("add-to-card", help="add the RSSA extension line to an Agent Card file, in place")
+    a.add_argument("card")
+    a.add_argument("--feed", required=True)
+    a.add_argument("--key")
+    a.add_argument("--modules")
+    sc = sub.add_parser("sign-card", help="sign an Agent Card (A2A native signatures field), in place")
+    sc.add_argument("card")
+    sc.add_argument("--key", required=True)
+    v = sub.add_parser("verify", help="fetch a feed and verify every signed entry")
+    v.add_argument("url")
+    p = sub.add_parser("sign-policy", help="sign a group policy.json in place and write roster.opml beside it")
+    p.add_argument("policy")
+    p.add_argument("--key", required=True)
+    args = ap.parse_args(argv)
+
+    if args.cmd == "keygen":
+        if os.path.exists(args.out):
+            print(f"rssa: {args.out} exists; refusing to overwrite a key", file=sys.stderr)
+            return 2
+        key = generate_key()
+        fd = os.open(args.out, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "w") as f:
+            json.dump(key.private_jwk, f, indent=2)
+        print(f"Private key written to {args.out}. Keep it secret; load it at runtime with rssa.load_key() or RSSA_KEY.", file=sys.stderr)
+        print("Paste this into your Agent Card's RSSA params as \"keys\":", file=sys.stderr)
+        print(json.dumps(key.public_jwks(), indent=2))
+        return 0
+    if args.cmd == "add-to-card":
+        with open(args.card, encoding="utf-8") as f:
+            card = json.load(f)
+        key = load_key(args.key) if args.key else None
+        modules = args.modules.split(",") if args.modules else (["sign"] if key else None)
+        card = with_rssa(card, feed=args.feed, modules=modules, keys=key.public_jwks() if key else None)
+        with open(args.card, "w", encoding="utf-8") as f:
+            json.dump(card, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        print(f"Added the RSSA extension to {args.card}. Next: publish {args.feed}, then sign the card (rssa sign-card) and run: rssa validate <your agent URL>")
+        return 0
+    if args.cmd == "sign-card":
+        with open(args.card, encoding="utf-8") as f:
+            card = json.load(f)
+        signed = sign_card(card, load_key(args.key))  # before opening for write, so a bad key can't truncate the card
+        with open(args.card, "w", encoding="utf-8") as f:
+            json.dump(signed, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        print(f"Signed {args.card}. Re-sign after every change to the card.")
+        return 0
+    if args.cmd == "verify":
+        r = read_feed(args.url, require_signatures=False)
+        bad = 0
+        for e in r.entries:
+            mark = "OK " if e.verified else ("-  " if not e.entry.sig else "BAD")
+            bad += bool(e.entry.sig and not e.verified)
+            print(f"{mark} {e.entry.id} {e.entry.type or ''}")
+            for c in e.checks:
+                if not c.ok:
+                    print(f"      {c.message}")
+        for msg in r.problems:
+            print(f"WARN {msg}")
+        return 1 if bad or r.problems else 0
+    if args.cmd == "sign-policy":
+        with open(args.policy, encoding="utf-8") as f:
+            policy = strict_parse(f.read())
+        signed = sign_policy(policy, load_key(args.key))
+        with open(args.policy, "w", encoding="utf-8") as f:
+            json.dump(signed, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        opml = os.path.join(os.path.dirname(args.policy) or ".", "roster.opml")
+        with open(opml, "w", encoding="utf-8") as f:
+            f.write(roster_opml(signed))
+        print(f"Signed {args.policy} (version {signed['version']}) and wrote {opml}. Bump version on every change.")
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rssa-0.1.1/rssa/agent.py

@@ -0,0 +1,260 @@
+"""High-level helpers: the Agent Card line, publishing, reading and local filtering."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .feed import Entry, ParsedFeed, atom_xml, json_feed, parse_feed, rss_xml
+from .keys import Fetch, Key, get_json, http_get, resolve_keys
+from .sign import Check, sign_entry, verify_entry
+
+EXT_URI = "https://rssa.getvda.ai/ext/v0.1"
+EXT_PREFIX = "https://rssa.getvda.ai/ext/"
+USER_AGENT = "rssa-sdk-py/0.1 (+https://rssa.getvda.ai)"
+
+
+def card_extension(feed: str, modules: Optional[list[str]] = None, hub: Optional[str] = None,
+                   groups: Optional[list[str]] = None, keys: Any = None) -> dict:
+    """The one Agent Card line. Put it in card["capabilities"]["extensions"]."""
+    params: dict = {"feed": feed}
+    if modules:
+        params["modules"] = modules
+    if hub:
+        params["hub"] = hub
+    if groups:
+        params["groups"] = groups
+    if keys:
+        params["keys"] = keys
+    return {"uri": EXT_URI, "description": "RSSA: this agent's feed and modules", "required": False, "params": params}
+
+
+def with_rssa(card: dict, **params) -> dict:
+    """Returns a copy of an Agent Card with the RSSA extension added or replaced."""
+    caps = dict(card.get("capabilities") or {})
+    exts = [e for e in caps.get("extensions", []) if not str(e.get("uri", "")).startswith(EXT_PREFIX)]
+    caps["extensions"] = exts + [card_extension(**params)]
+    return {**card, "capabilities": caps}
+
+
+def find_rssa(card: Any) -> Optional[dict]:
+    for e in ((card or {}).get("capabilities") or {}).get("extensions", []):
+        if str(e.get("uri", "")).startswith(EXT_PREFIX):
+            return e
+    return None
+
+
+def card_modules(card: Any) -> list[str]:
+    ext = find_rssa(card)
+    return [str(m).split("@")[0] for m in ((ext or {}).get("params") or {}).get("modules", [])]
+
+
+def sign_card(card: dict, key: Key) -> dict:
+    """Signs an Agent Card with A2A's native `signatures` field (JWS over the RFC 8785 canonical card).
+    Re-sign after every change to the card."""
+    from .canonical import canonicalize
+    from .keys import sign_detached
+
+    body = {k: v for k, v in card.items() if k != "signatures"}
+    protected, _, signature = sign_detached(canonicalize(body).encode("utf-8"), key).split(".")
+    return {**body, "signatures": [{"protected": protected, "signature": signature}]}
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def entry(title: Optional[str] = None, summary: Optional[str] = None, content: Optional[str] = None, *,
+          type: Optional[str] = None, to: Optional[str] = None, source: Optional[str] = None,
+          in_reply_to: Optional[str] = None, reaction: Optional[str] = None, id: Optional[str] = None,
+          updated: Optional[str] = None, link: Optional[str] = None, content_type: Optional[str] = None) -> Entry:
+    """A new entry with a urn:uuid id and the current time (whole seconds) unless given."""
+    return Entry(id=id or f"urn:uuid:{uuid.uuid4()}", updated=updated or now(), title=title, summary=summary, content=content,
+                 content_type=content_type, link=link, type=type, to=to, source=source, in_reply_to=in_reply_to, reaction=reaction)
+
+
+# Content-Type to serve each format with.
+MEDIA_TYPES = {"atom": "application/atom+xml", "rss": "application/rss+xml", "json": "application/feed+json"}
+
+
+def build_feed(feed_url: str, title: str, entries: list[Entry], key: Optional[Key] = None, card_url: Optional[str] = None,
+               hub_url: Optional[str] = None, author: Optional[str] = None, format: str = "atom") -> str:
+    """Builds a complete feed: format "atom" (default), "rss" (RSS 2.0) or "json" (JSON Feed 1.1).
+    With a key every entry is signed. Returns a string: store it wherever your platform keeps
+    files (disk, GCS, S3, a route handler) and serve it with MEDIA_TYPES[format]."""
+    if format not in MEDIA_TYPES:
+        raise ValueError(f"format must be one of {sorted(MEDIA_TYPES)}")
+    seen = set()
+    for e in entries:
+        if e.id in seen:
+            raise ValueError(f"duplicate entry id {e.id}")
+        seen.add(e.id)
+    ordered = sorted(entries, key=lambda e: e.updated, reverse=True)
+    if key:
+        ordered = [sign_entry(e, feed_url, key) for e in ordered]
+    if format == "rss":
+        return rss_xml(feed_url, title, ordered, card_url=card_url, hub_url=hub_url)
+    if format == "json":
+        return json_feed(feed_url, title, ordered, card_url=card_url, hub_url=hub_url)
+    return atom_xml(feed_url, title, ordered, card_url=card_url, hub_url=hub_url, author=author)
+
+
+def ping_hub(hub_url: str, feed_url: str) -> int:
+    """Tells a WebSub hub the feed changed. Never raises; returns the HTTP status (0 on network error)."""
+    import urllib.parse
+    import urllib.request
+
+    data = urllib.parse.urlencode({"hub.mode": "publish", "hub.url": feed_url}).encode()
+    try:
+        with urllib.request.urlopen(urllib.request.Request(hub_url, data=data, headers={"User-Agent": USER_AGENT}), timeout=10) as r:
+            return r.status
+    except Exception as e:  # noqa: BLE001
+        return getattr(e, "code", 0)
+
+
+@dataclass
+class ReadEntry:
+    entry: Entry
+    verified: bool
+    source: str  # the feed the entry is attributed to
+    checks: list[Check] = field(default_factory=list)
+
+    def __getattr__(self, name):  # entry fields read through: r.type, r.summary …
+        return getattr(self.entry, name)
+
+
+@dataclass
+class FeedRead:
+    feed: ParsedFeed
+    card: Optional[dict]
+    keys: list[dict]
+    entries: list[ReadEntry]
+    problems: list[str]
+
+
+def read_feed(url: str, fetch: Optional[Fetch] = None, require_signatures: Optional[bool] = None, reader_card: Optional[str] = None) -> FeedRead:
+    """Fetches a feed, follows rel=describedby to the card, checks it points back, verifies signatures.
+    Pass reader_card (your own Agent Card URL) so publishers and hubs can count real subscribers."""
+    ua = f"{USER_AGENT} reader={reader_card}" if reader_card else USER_AGENT
+    fetch = fetch or (lambda u: http_get(u, accept="application/atom+xml, application/rss+xml, application/feed+json, application/json", user_agent=ua))
+    status, text = fetch(url)
+    if status != 200:
+        raise ValueError(f"GET {url} returned {status}")
+    feed = parse_feed(text)
+    problems = list(feed.problems)
+    feed_url = feed.self_url or url
+    card, keys = None, []
+    no_keys_reason = None if feed.card_url else "the feed has no rel=describedby link to an Agent Card, so there are no keys to check against"
+    if feed.card_url:
+        try:
+            card = get_json(feed.card_url, fetch)
+            ext = find_rssa(card)
+            if not ext:
+                problems.append(f"card {feed.card_url} has no RSSA extension")
+                no_keys_reason = f"the Agent Card {feed.card_url} has no RSS-A line yet, so it does not vouch for this feed or publish keys"
+            elif ext["params"].get("feed") != feed_url:
+                problems.append(f"card names feed {ext['params'].get('feed')}, not {feed_url} — it does not vouch for this feed")
+                no_keys_reason = f"the Agent Card names feed {ext['params'].get('feed')}, not this one, so its keys do not apply here"
+            elif ext["params"].get("keys"):
+                keys = resolve_keys(ext["params"]["keys"], fetch)
+        except Exception as e:  # noqa: BLE001
+            problems.append(f"card: {e}")
+    if require_signatures is None:
+        require_signatures = "sign" in card_modules(card)
+    out = []
+    for e in feed.entries:
+        attributed = e.source_feed or feed_url
+        if not e.sig:
+            if require_signatures:
+                problems.append(f"dropped unsigned entry {e.id}")
+            else:
+                out.append(ReadEntry(e, False, attributed))
+            continue
+        k = keys
+        if e.source_feed and e.source_feed != feed_url and e.source_card:
+            try:
+                c = get_json(e.source_card, fetch)
+                x = find_rssa(c)
+                k = resolve_keys(x["params"]["keys"], fetch) if x and x["params"].get("feed") == e.source_feed and x["params"].get("keys") else []
+            except Exception:  # noqa: BLE001
+                k = []
+        v = verify_entry(e, attributed, k)
+        if not k and attributed == feed_url and no_keys_reason:
+            # Say why there is nothing to verify against, instead of a bare key-id error.
+            v.checks = [c for c in v.checks if c.code != "signature"] + [Check(False, "signature", f"cannot verify: {no_keys_reason}")]
+        if v.ok or not require_signatures:
+            out.append(ReadEntry(e, v.ok, attributed, v.checks))
+        else:
+            problems.append(f"dropped entry {e.id}: " + "; ".join(c.message for c in v.checks if not c.ok))
+    return FeedRead(feed, card, keys, out, problems)
+
+
+def local_filter(entries: list[ReadEntry], signed_only: bool = False, types: Optional[list[str]] = None,
+                 to: Optional[list[str]] = None, sources: Optional[list[str]] = None) -> list[ReadEntry]:
+    """Consumer-side guardrail, applied with plain code before any model reads an entry.
+    Type patterns ending in "." match prefixes ("exception."). Entries without rssa:to count as "group"."""
+    def type_ok(t):
+        return types is None or (t is not None and any(t == p or (p.endswith(".") and t.startswith(p)) for p in types))
+    return [r for r in entries
+            if (not signed_only or r.verified) and type_ok(r.entry.type)
+            and (to is None or (r.entry.to or "group") in to) and (sources is None or r.source in sources)]
+
+
+@dataclass
+class GroupRead:
+    policy: dict
+    policy_verified: bool
+    entries: list[ReadEntry]  # newest first
+    problems: list[str]
+
+
+def read_group(policy_url: str, fetch: Optional[Fetch] = None, reader_card: Optional[str] = None) -> GroupRead:
+    """Hubless group reading (open groups, two-party links, or checking a hub): fetches and
+    verifies the policy, reads every member feed, checks two-way membership, then applies
+    the group's policy in time order. Dropped entries are listed in `problems` with the reason."""
+    from datetime import datetime as _dt
+
+    from .policy import check_entry, effective_settings, verify_policy
+
+    ua = f"{USER_AGENT} reader={reader_card}" if reader_card else USER_AGENT
+    fetch = fetch or (lambda u: http_get(u, accept="application/atom+xml, application/rss+xml, application/feed+json, application/json", user_agent=ua))
+    policy = get_json(policy_url, fetch)
+    problems: list[str] = []
+    pok, perr = verify_policy(policy, fetch)
+    if not pok:
+        problems.append(f"policy signature: {perr}")
+    s = effective_settings(policy)
+    refs = {policy.get("group"), policy_url}
+    every: list[ReadEntry] = []
+    for m in policy.get("members", []):
+        try:
+            fr = read_feed(m["feed"], fetch=fetch, require_signatures=s["signatures"] == "required" or None)
+        except Exception as e:  # noqa: BLE001
+            problems.append(f"{m['feed']}: {e}")
+            continue
+        groups = (((find_rssa(fr.card) or {}).get("params")) or {}).get("groups") or []
+        if not refs & set(groups):
+            problems.append(f"{m['feed']}: its Agent Card does not list this group — not a member (two-way membership)")
+            continue
+        problems += [f"{m['feed']}: {p}" for p in fr.problems]
+        every += fr.entries
+    ts = lambda r: _dt.fromisoformat(r.entry.updated.replace("Z", "+00:00")).timestamp()
+    every.sort(key=ts)
+    depth: dict[str, int] = {}
+    root: dict[str, str] = {}
+    last: dict[str, float] = {}
+    kept: list[ReadEntry] = []
+    for r in every:
+        e = r.entry
+        v = check_entry(e, r.source, s, depth_of=depth.get, root_of=root.get, last_post=lambda f, rt: last.get(f"{f} {rt}"))
+        if v:
+            problems.append(f"dropped {e.id}: " + "; ".join(m for _, m in v))
+            continue
+        d = depth.get(e.in_reply_to, 0) + 1 if e.in_reply_to else 0
+        rt = root.get(e.in_reply_to, e.in_reply_to) if e.in_reply_to else e.id
+        depth[e.id], root[e.id] = d, rt
+        last[f"{r.source} {rt}"] = ts(r)
+        kept.append(r)
+    return GroupRead(policy, pok, list(reversed(kept)), problems)