factmesh 0.1.0__py3-none-any.whl

factmesh/__init__.py

@@ -0,0 +1,3 @@
+"""Reference client for the claim exchange protocol (SPEC.md)."""
+
+__version__ = "0.1.0"

factmesh/check.py

@@ -0,0 +1,155 @@
+"""Running a claim's check against the web (SPEC.md §4.4, §4.5)."""
+
+import ipaddress
+import json
+from dataclasses import dataclass
+from urllib.parse import urljoin
+
+from .claim import Rejected, check_binding, url_parts
+
+MAX_REDIRECTS = 3
+REDIRECT_STATUSES = {301, 302, 303, 307, 308}
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    headers: dict
+    body: bytes
+
+
+class FetchError(Exception):
+    """No conclusion: network failure, timeout, or size limit."""
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    result: str          # "pass", "fail", or "error"
+    detail: str = ""
+    final_url: str = ""
+
+
+def is_public(address):
+    ip = ipaddress.ip_address(address)
+    if ip.version == 6 and ip.ipv4_mapped:
+        ip = ip.ipv4_mapped
+    return ip.is_global and not ip.is_multicast
+
+
+def _resolve_pointer(doc, pointer):
+    if pointer == "":
+        return doc
+    node = doc
+    for raw in pointer[1:].split("/"):
+        token = raw.replace("~1", "/").replace("~0", "~")
+        if isinstance(node, dict) and token in node:
+            node = node[token]
+        elif (isinstance(node, list) and token.isdigit()
+              and (token == "0" or not token.startswith("0")) and int(token) < len(node)):
+            node = node[int(token)]
+        else:
+            raise KeyError(pointer)
+    return node
+
+
+def json_equal(a, b):
+    """Strict JSON equality for scalars: bool is not a number, 1 == 1.0."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return type(a) is type(b) and a == b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return a == b
+    return type(a) is type(b) and a == b
+
+
+def _compare(check, resp):
+    kind = check["kind"]
+    if kind == "http-status":
+        ok = resp.status == check["expect"]
+        return CheckResult("pass" if ok else "fail", f"status {resp.status}")
+    if resp.status != 200:
+        return CheckResult("fail", f"status {resp.status}")
+    try:
+        text = resp.body.decode("utf-8")
+    except UnicodeDecodeError:
+        return CheckResult("fail", "body is not UTF-8")
+    if kind == "text-contains":
+        ok = check["expect"] in text
+        return CheckResult("pass" if ok else "fail", "text found" if ok else "text not found")
+    try:
+        doc = json.loads(text)
+    except ValueError:
+        return CheckResult("fail", "body is not JSON")
+    except RecursionError:
+        return CheckResult("fail", "JSON nested too deeply")
+    try:
+        value = _resolve_pointer(doc, check["pointer"])
+    except KeyError:
+        return CheckResult("fail", "pointer does not resolve")
+    if isinstance(value, (dict, list)):
+        return CheckResult("fail", "pointer refers to an object or array")
+    ok = json_equal(value, check["expect"])
+    return CheckResult("pass" if ok else "fail", f"value {json.dumps(value)[:80]}")
+
+
+def run_check(topic, check, fetcher):
+    """Run one check. `fetcher` provides resolve(host) and get(url, address).
+
+    Exceptions other than FetchError propagate, so a test harness can stop a
+    receiver that makes a request it should not.
+    """
+    got = fetch(topic, check["url"], check["kind"] != "http-status", fetcher)
+    if isinstance(got, CheckResult):
+        return got
+    resp, url = got
+    r = _compare(check, resp)
+    return CheckResult(r.result, r.detail, url)
+
+
+def observe_json(topic, url, pointer, fetcher):
+    """The current value at `pointer` in the JSON at `url`, fetched under the
+    same rules as a check. Returns (value, None) or (None, reason)."""
+    got = fetch(topic, url, True, fetcher)
+    if isinstance(got, CheckResult):
+        return None, got.detail
+    resp, _ = got
+    if resp.status != 200:
+        return None, f"status {resp.status}"
+    try:
+        value = _resolve_pointer(json.loads(resp.body.decode("utf-8")), pointer)
+    except (ValueError, KeyError, RecursionError, UnicodeDecodeError):
+        return None, "no value at pointer"
+    if isinstance(value, (dict, list)):
+        return None, "pointer refers to an object or array"
+    return value, None
+
+
+def fetch(topic, url, follow, fetcher):
+    """GET `url` under SPEC.md §4.4, following redirects inside the topic
+    binding if `follow`. Returns (Response, final url) or an error
+    CheckResult."""
+    for hop in range(MAX_REDIRECTS + 1):
+        host, _ = url_parts(url)
+        try:
+            addresses = fetcher.resolve(host)
+        except FetchError as e:
+            return CheckResult("error", f"resolve {host}: {e}", url)
+        if not addresses or not all(is_public(a) for a in addresses):
+            return CheckResult("error", f"{host} resolves to a non-public address", url)
+        try:
+            resp = fetcher.get(url, addresses[0])
+        except FetchError as e:
+            return CheckResult("error", str(e), url)
+
+        if not (follow and resp.status in REDIRECT_STATUSES):
+            return resp, url
+        if hop == MAX_REDIRECTS:
+            return CheckResult("error", "too many redirects", url)
+        location = resp.headers.get("location")
+        if not location:
+            return CheckResult("error", "redirect without location", url)
+        url = urljoin(url, location)
+        try:
+            check_binding(topic, url)
+        except Rejected as e:
+            return CheckResult("error", f"redirect not allowed: {e}", url)
+    raise AssertionError("unreachable")

factmesh/claim.py

@@ -0,0 +1,279 @@
+"""Claim files: parsing and the offline rules of SPEC.md §2–§4."""
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+
+import yaml
+
+MAX_CONTENT_BYTES = 8192
+MAX_LIFETIME = timedelta(days=7)
+MAX_DEPTH = 4
+MAX_URL_LENGTH = 300
+ALLOWLIST = frozenset({"registry.npmjs.org", "pypi.org", "api.github.com", "github.com"})
+
+CHECK_FIELDS = {
+    "http-status": {"kind", "url", "expect"},
+    "json-field-equals": {"kind", "url", "pointer", "expect"},
+    "text-contains": {"kind", "url", "expect"},
+}
+QUESTION_FIELDS = {
+    "http-status": ("kind", "url"),
+    "json-field-equals": ("kind", "url", "pointer"),
+    "text-contains": ("kind", "url", "expect"),
+}
+
+_NPM_PART = r"[a-z0-9][a-z0-9._~-]{0,213}"
+TOPIC_PATTERNS = {
+    "npm": re.compile(rf"(?:@{_NPM_PART}/)?{_NPM_PART}"),
+    "pypi": re.compile(r"[a-z0-9](?:[a-z0-9]|-(?!-))*(?<!-)"),
+    "github": re.compile(r"[a-z0-9](?:[a-z0-9]|-(?!-)){0,38}/[a-z0-9._-]{1,100}"),
+}
+_TIME_STRING = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z")
+
+
+class Rejected(Exception):
+    """A claim or event broke a rule. `reason` is a SPEC.md §7 code."""
+
+    def __init__(self, reason, detail=""):
+        super().__init__(f"{reason}: {detail}" if detail else reason)
+        self.reason = reason
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class Claim:
+    topic: str
+    check: dict
+    generated_by: str
+    generated_at: datetime
+    stale_after: datetime
+    status: str
+    header: dict = field(repr=False)
+    content: str = field(repr=False)
+
+    @property
+    def key(self):
+        return claim_key(self.check)
+
+    @property
+    def retracted(self):
+        return self.status == "deprecated"
+
+
+# --- YAML -------------------------------------------------------------------
+
+class _StrictLoader(yaml.SafeLoader):
+    """SafeLoader that refuses repeated mapping keys."""
+
+
+def _construct_mapping(loader, node, deep=False):
+    seen = set()
+    for key_node, _ in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if key in seen:
+            raise Rejected("bad-header", f"repeated key {key!r}")
+        seen.add(key)
+    return yaml.SafeLoader.construct_mapping(loader, node, deep=deep)
+
+
+_StrictLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+                              _construct_mapping)
+
+
+def _depth(value):
+    if isinstance(value, dict):
+        return 1 + max((_depth(v) for v in value.values()), default=0)
+    if isinstance(value, list):
+        return 1 + max((_depth(v) for v in value), default=0)
+    return 0
+
+
+def parse_header(content):
+    """Split a claim file and load its YAML header (SPEC.md §2.1)."""
+    if not content.startswith("---\n"):
+        raise Rejected("bad-header", "file does not start with a --- line")
+    lines = content.split("\n")
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        raise Rejected("bad-header", "no closing --- line") from None
+    text = "\n".join(lines[1:end])
+    try:
+        for token in yaml.scan(text, Loader=yaml.SafeLoader):
+            if isinstance(token, (yaml.AnchorToken, yaml.AliasToken, yaml.TagToken)):
+                raise Rejected("bad-header", f"{type(token).__name__[:-5].lower()} not allowed")
+        header = yaml.load(text, Loader=_StrictLoader)
+    except yaml.YAMLError as e:
+        raise Rejected("bad-header", str(e).splitlines()[0]) from None
+    if not isinstance(header, dict):
+        raise Rejected("bad-header", "header is not a mapping")
+    if _depth(header) > MAX_DEPTH:
+        raise Rejected("bad-header", f"nests deeper than {MAX_DEPTH} levels")
+    return header
+
+
+# --- fields -----------------------------------------------------------------
+
+def parse_time(value, name):
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() != timedelta(0):
+            raise Rejected("bad-field", f"{name} must be UTC with a Z suffix")
+        return value.astimezone(timezone.utc)
+    if isinstance(value, str) and _TIME_STRING.fullmatch(value):
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    raise Rejected("bad-field", f"{name} is not a UTC date-time")
+
+
+def _fields(header):
+    if header.get("type") != "Claim":
+        raise Rejected("bad-field", "type is not Claim")
+    for name in ("topic", "check", "generated", "stale_after"):
+        if name not in header:
+            raise Rejected("bad-field", f"missing {name}")
+    if not isinstance(header["topic"], str):
+        raise Rejected("bad-field", "topic is not a string")
+    gen = header["generated"]
+    if not isinstance(gen, dict) or not isinstance(gen.get("by"), str) or not gen["by"]:
+        raise Rejected("bad-field", "generated.by missing")
+    if "at" not in gen:
+        raise Rejected("bad-field", "generated.at missing")
+    generated_at = parse_time(gen["at"], "generated.at")
+    stale_after = parse_time(header["stale_after"], "stale_after")
+    if stale_after <= generated_at:
+        raise Rejected("bad-field", "stale_after is not after generated.at")
+    if stale_after - generated_at > MAX_LIFETIME:
+        raise Rejected("bad-field", "lifetime over 7 days")
+    status = header.get("status", "stable")
+    if status not in ("stable", "deprecated"):
+        raise Rejected("bad-field", f"unknown status {status!r}")
+    for name, kind in (("title", str), ("tags", list), ("sources", list)):
+        if name in header and not isinstance(header[name], kind):
+            raise Rejected("bad-field", f"{name} has the wrong type")
+    return gen["by"], generated_at, stale_after, status
+
+
+def validate_topic(topic):
+    prefix, sep, name = topic.partition(":")
+    pattern = TOPIC_PATTERNS.get(prefix)
+    if not sep or pattern is None or not pattern.fullmatch(name):
+        raise Rejected("bad-topic", topic)
+    if prefix == "github" and name.split("/")[1] in (".", ".."):
+        raise Rejected("bad-topic", topic)
+    return prefix, name
+
+
+def _is_json_scalar(v):
+    return v is None or isinstance(v, (str, bool, int, float))
+
+
+def validate_check(check):
+    if not isinstance(check, dict):
+        raise Rejected("bad-check", "check is not a mapping")
+    kind = check.get("kind")
+    if kind not in CHECK_FIELDS:
+        raise Rejected("bad-check", f"unknown kind {kind!r}")
+    if set(check) != CHECK_FIELDS[kind]:
+        raise Rejected("bad-check", f"fields must be exactly {sorted(CHECK_FIELDS[kind])}")
+    if not isinstance(check["url"], str):
+        raise Rejected("bad-check", "url is not a string")
+    expect = check["expect"]
+    if kind == "http-status":
+        if not isinstance(expect, int) or isinstance(expect, bool) or not 100 <= expect <= 599:
+            raise Rejected("bad-check", "expect must be an integer 100-599")
+    elif kind == "json-field-equals":
+        pointer = check["pointer"]
+        if not isinstance(pointer, str) or (pointer and not pointer.startswith("/")):
+            raise Rejected("bad-check", "pointer is not a JSON Pointer")
+        if not _is_json_scalar(expect):
+            raise Rejected("bad-check", "expect must be a JSON scalar")
+    elif not isinstance(expect, str) or not 8 <= len(expect) <= 200:
+        raise Rejected("bad-check", "expect must be a string of 8-200 characters")
+
+
+# --- URLs -------------------------------------------------------------------
+
+def url_parts(url):
+    """Return (host, path segments) or raise bad-url (SPEC.md §4.2).
+
+    Works on the string as written: no normalization, so `..` and encoded
+    characters cannot slip past the binding rules.
+    """
+    if len(url) > MAX_URL_LENGTH:
+        raise Rejected("bad-url", f"longer than {MAX_URL_LENGTH} characters")
+    if not url.startswith("https://"):
+        raise Rejected("bad-url", "scheme must be https")
+    if any(c in url for c in "%?#") or any(c.isspace() for c in url):
+        raise Rejected("bad-url", "no %, query, fragment, or whitespace allowed")
+    rest = url[len("https://"):]
+    host, slash, path = rest.partition("/")
+    if "@" in host or ":" in host:
+        raise Rejected("bad-url", "no user information or port allowed")
+    if host not in ALLOWLIST:
+        raise Rejected("bad-url", f"host {host!r} not on the allowlist")
+    return host, path.split("/") if slash else []
+
+
+def check_binding(topic, url):
+    """Raise topic-mismatch unless `url` is an allowed path for `topic` (§4.3)."""
+    prefix, name = validate_topic(topic)
+    host, segs = url_parts(url)
+    if not segs or any(s in ("", ".", "..") for s in segs):
+        raise Rejected("topic-mismatch", "empty or dot path segment")
+    name_segs = name.split("/")
+    n = len(name_segs)
+
+    ok = False
+    if prefix == "npm" and host == "registry.npmjs.org":
+        ok = (segs == ["-", "package", *name_segs, "dist-tags"]
+              or segs[:n] == name_segs and len(segs) in (n, n + 1))
+    elif prefix == "pypi" and host == "pypi.org":
+        ok = segs[:2] == ["pypi", name] and segs[-1] == "json" and len(segs) in (3, 4)
+    elif prefix == "github" and host == "api.github.com":
+        ok = segs[:3] == ["repos", *name_segs]
+    elif prefix == "github" and host == "github.com":
+        ok = segs[:2] == name_segs
+    if not ok:
+        raise Rejected("topic-mismatch", f"{url} is not allowed for {topic}")
+
+
+# --- whole claim ------------------------------------------------------------
+
+def claim_key(check):
+    """First 32 hex chars of SHA-256 over the check's question fields (§5.1)."""
+    names = QUESTION_FIELDS.get(check.get("kind"), ("kind", "url"))
+    q = {k: check[k] for k in names if k in check}
+    canon = json.dumps(q, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(canon.encode()).hexdigest()[:32]
+
+
+def parse_claim(content):
+    """Parse and statically validate a claim file (SPEC.md §7 steps 5-11)."""
+    if len(content.encode()) > MAX_CONTENT_BYTES:
+        raise Rejected("too-large", f"over {MAX_CONTENT_BYTES} bytes")
+    header = parse_header(content)
+    by, generated_at, stale_after, status = _fields(header)
+    validate_topic(header["topic"])
+    validate_check(header["check"])
+    url_parts(header["check"]["url"])
+    check_binding(header["topic"], header["check"]["url"])
+    return Claim(topic=header["topic"], check=header["check"], generated_by=by,
+                 generated_at=generated_at, stale_after=stale_after, status=status,
+                 header=header, content=content)
+
+
+def claim_text(topic, kind, url, expect, pointer, hours, agent, now: datetime):
+    """Build a claim file. Values are written as JSON scalars, which YAML
+    reads back unchanged."""
+    z = lambda t: t.strftime("%Y-%m-%dT%H:%M:%SZ")
+    check = [f"  kind: {json.dumps(kind)}", f"  url: {json.dumps(url)}"]
+    if pointer is not None:
+        check.append(f"  pointer: {json.dumps(pointer)}")
+    check.append(f"  expect: {json.dumps(expect)}")
+    return ("---\ntype: Claim\n"
+            f"topic: {json.dumps(topic)}\n"
+            f"generated: {{ by: {json.dumps(agent)}, at: {z(now)} }}\n"
+            f"stale_after: {z(now + timedelta(hours=hours))}\n"
+            "check:\n" + "\n".join(check) + "\n---\n")

factmesh/cli.py

@@ -0,0 +1,181 @@
+"""Command line: check, sign, publish, and look up claims; run the MCP server;
+show or rotate the key."""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import keys
+from .check import run_check
+from .claim import Rejected, parse_claim
+from .fetch import Fetcher
+from .receiver import Receiver
+from .relay import RelayPool
+from .reputation import Reputation
+from .store import Store
+from .validate import validate_event, validate_file
+
+EXIT_CODES = {"pass": 0, "fail": 1, "rejected": 2, "error": 3, "retracted": 4}
+
+
+def _now(value):
+    if value is None:
+        return datetime.now(timezone.utc)
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def cmd_check(args):
+    text = Path(args.path).read_text()
+    now = _now(args.now)
+    if args.path.endswith(".json"):
+        doc = json.loads(text)
+        result = validate_event(doc.get("event", doc), now, Fetcher())
+    else:
+        result = validate_file(text, now, Fetcher())
+    line = result.result
+    if result.reason:
+        line += f": {result.reason}"
+    if result.detail:
+        line += f" ({result.detail})"
+    print(line)
+    return EXIT_CODES[result.result]
+
+
+def cmd_sign(args):
+    try:
+        claim = parse_claim(Path(args.path).read_text())
+    except Rejected as e:
+        print(f"not signed: {e}", file=sys.stderr)
+        return EXIT_CODES["rejected"]
+    ev = keys.load_signer().claim_event(claim, int(claim.generated_at.timestamp()))
+    print(json.dumps(ev, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_publish(args):
+    try:
+        claim = parse_claim(Path(args.path).read_text())
+    except Rejected as e:
+        print(f"not published: {e}", file=sys.stderr)
+        return EXIT_CODES["rejected"]
+    if claim.retracted:
+        print("publishing a retraction; its check is not run", file=sys.stderr)
+    else:
+        r = run_check(claim.topic, claim.check, Fetcher())
+        if r.result != "pass":
+            print(f"not published: own check gave {r.result} ({r.detail})", file=sys.stderr)
+            return EXIT_CODES[r.result]
+    ev = keys.load_signer().claim_event(claim, int(claim.generated_at.timestamp()))
+    status = asyncio.run(RelayPool(args.relay or None).publish(ev))
+    for url, s in status.items():
+        print(f"{url}  {s}")
+    confirmed = sum(s == "confirmed" for s in status.values())
+    print(f"{confirmed} of {len(status)} relays confirmed event {ev['id']}")
+    return 0 if confirmed else EXIT_CODES["error"]
+
+
+def cmd_lookup(args):
+    receiver = Receiver(RelayPool(args.relay or None), Store(), Reputation(), Fetcher())
+    found, stats = asyncio.run(receiver.lookup(args.topic))
+    print(json.dumps({"facts": found, "stats": stats.__dict__}, indent=2))
+    return 0
+
+
+def cmd_seed(args):
+    from .event import Signer
+    from .seed import load_targets, run_seed
+    try:
+        targets = load_targets(args.packages)
+    except ValueError as e:
+        print(e, file=sys.stderr)
+        return 2
+    if args.key_env:
+        secret = os.environ.get(args.key_env, "").strip()
+        if len(secret) != 64:
+            print(f"{args.key_env} must hold a 64-character hex key", file=sys.stderr)
+            return 2
+        signer = Signer(bytes.fromhex(secret))
+    else:
+        signer = keys.load_signer()
+    report = asyncio.run(run_seed(targets, RelayPool(args.relay or None), signer, Fetcher(),
+                                  valid_hours=args.valid_hours,
+                                  refresh_hours=args.refresh_hours, dry_run=args.dry_run))
+    print(f"key {signer.pubkey}")
+    for topic, value in report.would_publish:
+        print(f"would publish  {topic} = {value}")
+    unconfirmed = 0
+    for topic, value, status in report.published:
+        ok = sum(s == "confirmed" for s in status.values())
+        unconfirmed += ok == 0
+        print(f"published      {topic} = {value}  ({ok}/{len(status)} relays)")
+    for topic, why in report.skipped:
+        print(f"skipped        {topic}: {why}")
+    print(f"{len(report.published)} published, {len(report.would_publish)} would publish, "
+          f"{len(report.fresh)} already current, {len(report.skipped)} skipped")
+    return 1 if unconfirmed else 0
+
+
+def cmd_mcp(args):
+    from .mcp_server import main as serve
+    serve()
+    return 0
+
+
+def cmd_key(args):
+    signer = keys.rotate() if args.rotate else keys.load_signer()
+    print(signer.pubkey)
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="factmesh", description=__doc__)
+    sub = ap.add_subparsers(required=True)
+
+    p = sub.add_parser("check", help="validate a claim file (.md) or event (.json) "
+                                     "and run its check against the web")
+    p.add_argument("path")
+    p.add_argument("--now", help="override the current time (ISO 8601, UTC)")
+    p.set_defaults(func=cmd_check)
+
+    p = sub.add_parser("sign", help="sign a claim file with this installation's key")
+    p.add_argument("path")
+    p.set_defaults(func=cmd_sign)
+
+    p = sub.add_parser("publish", help="check a claim file yourself, sign it, and "
+                                       "send it to relays")
+    p.add_argument("path")
+    p.add_argument("--relay", action="append", help="relay URL (repeatable)")
+    p.set_defaults(func=cmd_publish)
+
+    p = sub.add_parser("lookup", help="fetch, verify, and print facts for a topic")
+    p.add_argument("topic")
+    p.add_argument("--relay", action="append", help="relay URL (repeatable)")
+    p.set_defaults(func=cmd_lookup)
+
+    p = sub.add_parser("seed", help="publish latest-version claims for a package list")
+    p.add_argument("--packages", default="seed/packages.toml")
+    p.add_argument("--key-env", help="environment variable holding the signing key (hex)")
+    p.add_argument("--valid-hours", type=int, default=24)
+    p.add_argument("--refresh-hours", type=int, default=6,
+                   help="republish when the current claim expires within this many hours")
+    p.add_argument("--dry-run", action="store_true", help="show what would be published")
+    p.add_argument("--relay", action="append", help="relay URL (repeatable)")
+    p.set_defaults(func=cmd_seed)
+
+    p = sub.add_parser("mcp", help="run the MCP server on stdio, for agents")
+    p.set_defaults(func=cmd_mcp)
+
+    p = sub.add_parser("key", help="print this installation's public key")
+    p.add_argument("--rotate", action="store_true", help="replace it with a new key")
+    p.set_defaults(func=cmd_key)
+
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

factmesh/config.py

@@ -0,0 +1,48 @@
+"""User settings, in <home>/config.toml. Created with defaults on first use so
+the user can find and edit it."""
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import __version__
+from .home import home, write_atomic
+from .relay import DEFAULT_RELAYS
+
+DEFAULT_TEXT = f'''# factmesh client settings.
+
+# Let your agent publish claims to the network. Off by default: with it off,
+# the agent can look up and verify facts but never sends anything.
+publish = false
+
+# Relays to read from and publish to.
+relays = [
+{"".join(f'    "{r}",{chr(10)}' for r in DEFAULT_RELAYS)}]
+
+# How published claims name their author. Name the software, never a person.
+agent = "factmesh-mcp/{__version__}"
+'''
+
+
+@dataclass
+class Config:
+    path: Path
+    publish: bool = False
+    relays: list = field(default_factory=lambda: list(DEFAULT_RELAYS))
+    agent: str = f"factmesh-mcp/{__version__}"
+
+
+def load(path: Path | None = None) -> Config:
+    path = Path(path) if path else home() / "config.toml"
+    if not path.exists():
+        write_atomic(path, DEFAULT_TEXT.encode())
+    data = tomllib.loads(path.read_text())
+    cfg = Config(path=path)
+    if isinstance(data.get("publish"), bool):
+        cfg.publish = data["publish"]
+    if isinstance(data.get("relays"), list) and data["relays"]:
+        cfg.relays = [r for r in data["relays"]
+                      if isinstance(r, str) and r.startswith(("wss://", "ws://"))]
+    if isinstance(data.get("agent"), str) and data["agent"].strip():
+        cfg.agent = data["agent"].strip()
+    return cfg