lnfnt-a2a 0.1.0__py3-none-any.whl

a2a/__init__.py

@@ -0,0 +1,5 @@
+"""a2a package."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

a2a/access.py

@@ -0,0 +1,143 @@
+"""Record-level ACL + profile manifest (DESIGN-A2A-V05 §4, v0.5.0).
+
+Two orthogonal concepts:
+- access level (L1/L2/L3) — v0.4.10 contract: L1 visible to author only,
+  foreign L1 via --include-l1 with an audit event. UNCHANGED for records
+  without an `acl` field (no narrowing of pre-existing queries);
+- `acl` list on a record — explicit grants: profile names, `@all-lex`
+  (any profile in the manifest), `@owner` (record's owner/author).
+  Author/owner/recipient are always implicitly readable.
+
+profiles.json (bus root): identity manifest. Enforcement is only active
+when the manifest exists — legacy buses without it behave exactly as v0.4.10.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import util
+
+MANIFEST_NAME = "profiles.json"
+
+# user-feed is a publication channel, not a sender; listed in the manifest
+# as a channel. Known agent profiles at v0.5.0 introduction:
+DEFAULT_PEER_PROFILES = (
+    "coordinator",
+    "colleague",
+    "user-profile",
+    "support",
+    "agent-profile",
+    "infra",
+)
+DEFAULT_CHANNELS = ("user-feed",)
+
+
+def manifest_path() -> Path:
+    return util.HOME / MANIFEST_NAME
+
+
+def load_manifest_names() -> set[str] | None:
+    """Return known profile names, or None when no manifest governs this bus.
+
+    A corrupt manifest is treated as 'no manifest' for enforcement (fail
+    open on reads, doctor flags the corruption as an issue) — refusing to
+    run the whole bus because one JSON file broke would be worse.
+    """
+    path = manifest_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    profiles = data.get("profiles")
+    if not isinstance(profiles, list):
+        return None
+    names: set[str] = set()
+    for entry in profiles:
+        if isinstance(entry, str):
+            names.add(entry)
+        elif isinstance(entry, dict) and entry.get("name"):
+            names.add(str(entry["name"]))
+    return names
+
+
+def manifest_known(name: str) -> bool | None:
+    """True/False when a manifest governs, None when it does not exist."""
+    names = load_manifest_names()
+    if names is None:
+        return None
+    return name in names
+
+
+def enforce_known(name: str, role: str) -> None:
+    """Refuse unknown profiles when the bus has a manifest (A-01).
+
+    Self-declaration via env stays, but 'typo'd a name -> wrote into the
+    world' is closed: unknown author/recipient/owner = refusal.
+    """
+    known = manifest_known(name)
+    if known is False:
+        util.fail(util.EXIT_USAGE_ERROR, f"unknown_profile:{role}:{name}")
+
+
+def _implicit_grantees(rec: dict[str, Any]) -> set[str]:
+    grants = set()
+    for key in ("author", "owner", "to"):
+        val = rec.get(key)
+        if val:
+            grants.add(str(val))
+    return grants
+
+
+def may_read(rec: dict[str, Any], profile: str, include_l1: bool = False) -> bool:
+    """Single read predicate for all read commands (journal/mail/alerts/tasks).
+
+    - record with explicit acl: only acl tokens + implicit author/owner/to
+      may read; --include-l1 does NOT bypass an explicit acl;
+    - record without acl: v0.4.10 semantics preserved exactly —
+      L1 readable by author, foreign L1 only with include_l1 (caller must
+      log the audit event itself, as journal/read/search already do).
+    """
+    acl = rec.get("acl")
+    if isinstance(acl, list) and acl:
+        tokens = {str(t) for t in acl}
+        if profile in tokens or "@all-lex" in tokens:
+            return True
+        if "@owner" in tokens:
+            owner = str(rec.get("owner") or rec.get("author") or "")
+            if profile == owner:
+                return True
+        if profile in _implicit_grantees(rec):
+            return True
+        return False
+    if rec.get("access") == "L1":
+        if profile in _implicit_grantees(rec):
+            return True
+        return bool(include_l1)
+    return True
+
+
+def acl_only(rec: dict[str, Any], profile: str) -> bool:
+    """acl gate for path-scoped listings (mail inbox/outbox) where legacy
+    semantics imposed no access-level filter: only an explicit acl blocks."""
+    acl = rec.get("acl")
+    if isinstance(acl, list) and acl:
+        return may_read(rec, profile)
+    return True
+
+
+def write_default_manifest(path: Path | None = None) -> Path:
+    """Create profiles.json at the bus root (idempotent helper for setup)."""
+    target = path or manifest_path()
+    payload = {
+        "profiles": [
+            {"name": name, "role": "peer-agent"} for name in DEFAULT_PEER_PROFILES
+        ],
+        "channels": list(DEFAULT_CHANNELS),
+    }
+    util.write_atomically(target, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    return target

a2a/alerts.py

@@ -0,0 +1,155 @@
+"""Health alert commands."""
+
+from __future__ import annotations
+
+import shutil
+import time
+from argparse import Namespace
+from datetime import timedelta
+
+from . import schema, scrubber, util
+from . import access as acl_mod
+
+
+def cmd_alert_set(args: Namespace) -> None:
+    start = time.time()
+    profile = util.resolve_profile(args)
+    target = args.target
+    severity = args.severity
+    active_until = args.active_until
+    try:
+        if active_until.endswith("m"):
+            minutes = int(active_until[:-1])
+            until_dt = util.now_utc() + timedelta(minutes=minutes)
+        elif active_until.endswith("h"):
+            hours = int(active_until[:-1])
+            until_dt = util.now_utc() + timedelta(hours=hours)
+        elif active_until.endswith("d"):
+            days = int(active_until[:-1])
+            until_dt = util.now_utc() + timedelta(days=days)
+        else:
+            until_dt = util.parse_utc(active_until)
+    except Exception:
+        util.fail(util.EXIT_INVALID_RECORD, "invalid_active_until")
+
+    access = args.access or schema.DEFAULT_ACCESS["alert"]
+    meta = {
+        "type": "alert",
+        "author": profile,
+        "access": access,
+        "target": target,
+        "severity": severity,
+        "active_until": util.utc_iso(until_dt),
+    }
+    schema.apply_defaults(meta, "alert")
+
+    ok, err = schema.validate(meta, args.body or "")
+    if not ok:
+        util.fail(util.EXIT_INVALID_RECORD, err)
+
+    body = args.body or ""
+    text = util.join_front_matter(meta, body)
+    dirty, hits = scrubber.check(text)
+    if dirty:
+        try:
+            from . import quarantine as _q
+            _q.quarantine_payload(profile, text, hits)
+        except Exception:
+            pass
+        util.fail_hint(util.EXIT_ERROR, "secret_detected", "secret material detected; remove or redact before sending", "a2a alert set --target x --severity info --active-until 2026-12-31 body", {"hits": hits})
+
+    created = util.parse_utc(meta["created_at"])
+    path = util.record_path("alert", profile, access, created, meta["id"])
+    util.write_atomically(path, text)
+    util.ok({"id": meta["id"], "target": target, "severity": severity, "active_until": meta["active_until"]}, elapsed_ms=int((time.time() - start) * 1000))
+
+
+def cmd_alert_list(args: Namespace) -> None:
+    start = time.time()
+    now = util.now_utc()
+    profile = util.resolve_profile(args)
+    active = []
+    for rec, path in _iter_alerts():
+        # v0.5.0 (J-05): единый read-гейт; без acl-поля — прежняя семантика L1
+        if not acl_mod.may_read(rec, profile):
+            continue
+        try:
+            until = util.parse_utc(rec["active_until"])
+        except Exception:
+            continue
+        if until > now:
+            active.append({
+                "id": rec["id"],
+                "author": rec.get("author"),
+                "target": rec.get("target"),
+                "severity": rec.get("severity"),
+                "active_until": rec["active_until"],
+            })
+    util.ok({"active": active}, elapsed_ms=int((time.time() - start) * 1000))
+
+
+def _iter_alerts():
+    for path in util.list_files(util.HOME / "alerts"):
+        rec = util.read_record(path)
+        if rec:
+            yield rec, path
+
+
+def cmd_alert_purge_expired(args: Namespace) -> None:
+    start = time.time()
+    profile = util.resolve_profile(args)
+    now = util.now_utc()
+    dry_run = not bool(getattr(args, "yes", False))
+    if getattr(args, "dry_run", False):
+        dry_run = True
+
+    expired = []
+    moved = 0
+    expired_dir = util.HOME / ".state" / "expired"
+    for rec, path in _iter_alerts():
+        if not acl_mod.may_read(rec, profile):
+            continue
+        try:
+            until = util.parse_utc(rec["active_until"])
+        except Exception:
+            continue
+        if until > now:
+            continue
+        entry = {
+            "id": rec.get("id"),
+            "author": rec.get("author"),
+            "target": rec.get("target"),
+            "severity": rec.get("severity"),
+            "active_until": rec.get("active_until"),
+            "path": str(path),
+        }
+        expired.append(entry)
+        if not dry_run:
+            expired_dir.mkdir(parents=True, exist_ok=True)
+            dest = expired_dir / path.name
+            if dest.exists():
+                stem = path.stem
+                suffix = path.suffix
+                i = 1
+                while (expired_dir / f"{stem}_{i}{suffix}").exists():
+                    i += 1
+                dest = expired_dir / f"{stem}_{i}{suffix}"
+            shutil.move(str(path), str(dest))
+            entry["moved_to"] = str(dest)
+            moved += 1
+
+    ids = [e.get("id") for e in expired]
+    util.ok({
+        "expired": expired,
+        "expired_ids": ids,
+        "ids": ids,
+        "purged": 0 if dry_run else moved,
+        "purged_count": 0 if dry_run else moved,
+        "moved": moved,
+        "moved_count": moved,
+        "removed": 0 if dry_run else moved,
+        "removed_count": 0 if dry_run else moved,
+        "count": len(expired),
+        "expired_count": len(expired),
+        "dry_run": dry_run,
+    }, elapsed_ms=int((time.time() - start) * 1000))

a2a/auditlog.py

@@ -0,0 +1,44 @@
+"""Audit logging for a2a access events."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import scrubber, util
+
+
+def _scrub_value(value: Any) -> Any:
+    """v0.6.0 §1: канал audit.details — любое секретное значение редактируется
+    до записи (аудит-лог не должен становиться каналом утечки)."""
+    if isinstance(value, str):
+        clean, _ = scrubber.redact(value)
+        return clean
+    if isinstance(value, list):
+        return [_scrub_value(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _scrub_value(v) for k, v in value.items()}
+    return value
+
+
+def log(event: str, caller: str, target: str, details: dict[str, Any] | None = None) -> None:
+    entry = {
+        "ts": util.utc_iso(),
+        "event": event,
+        "caller": caller,
+        "target": scrubber.redact(str(target))[0],
+        "details": _scrub_value(details or {}),
+    }
+    path = util.HOME / ".state" / "audit.log"
+    util.ensure_dir(path)
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def read_logs() -> list[dict[str, Any]]:
+    path = util.HOME / ".state" / "audit.log"
+    if not path.exists():
+        return []
+    lines = path.read_text(encoding="utf-8").strip().splitlines()
+    return [json.loads(line) for line in lines if line.strip()]

a2a/backup.py

@@ -0,0 +1,193 @@
+"""Bus backup/restore (v0.6.0 §5, G-06).
+
+`a2a backup [--dest DIR]` — tar.gz шины (без .state, без самого каталога backups)
+с SHA256SUMS.txt внутри; имя файла — по дню (идемпотентно: повтор в тот же день
+перезаписывает дневной архив).
+
+`a2a backup --restore FILE [--yes]` — ПО УМОЛЧАНИЮ dry-run: отчёт со списком
+конфликтов ничего не меняет на диске. --yes применяет, НО никогда не затирает
+файл, чей локальный контент отличается И новее архивного — такие цели уходят в
+conflicts и пропускаются. Members с путями-ловушками (абсолютные, ../) — unsafe,
+не извлекаются. Целостность: содержимое сверяется с SHA256SUMS.txt внутри архива.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tarfile
+import time
+from io import BytesIO
+from pathlib import Path
+from typing import Any
+
+from . import util
+
+EXCLUDE_TOP = {".state", "backups", "wake"}
+SUMS_NAME = "SHA256SUMS.txt"
+
+
+def _iter_bus_files():
+    home = util.HOME
+    if not home.is_dir():
+        return
+    for p in sorted(home.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(home)
+        if rel.parts and rel.parts[0] in EXCLUDE_TOP:
+            continue
+        if p.name.endswith(".tmp"):
+            continue
+        yield p, str(rel)
+
+
+def _write_bytes(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile_mkstemp(str(path.parent), path.name + ".", ".tmp")
+    with os.fdopen(fd, "wb") as fh:
+        fh.write(data)
+        fh.flush()
+        os.fsync(fh.fileno())
+    os.replace(tmp_name, path)
+
+
+def tempfile_mkstemp(dir_: str, prefix: str, suffix: str) -> tuple[int, str]:
+    import tempfile
+    return tempfile.mkstemp(dir=dir_, prefix=prefix, suffix=suffix)
+
+
+def create(dest: str | None = None) -> dict:
+    dest_dir = Path(dest).expanduser() if dest else util.HOME / "backups"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    name = f"a2a-bus-{util.now_utc().strftime('%Y-%m-%d')}.tar.gz"
+    target = dest_dir / name
+    tmp = dest_dir / f"{name}.{os.getpid()}.tmp"
+    rows: list[str] = []
+    count = 0
+    with tarfile.open(tmp, "w:gz") as tf:
+        for p, rel in _iter_bus_files():
+            try:
+                data = p.read_bytes()
+            except Exception:
+                continue
+            sha = hashlib.sha256(data).hexdigest()
+            ti = tarfile.TarInfo(rel)
+            ti.size = len(data)
+            ti.mtime = p.stat().st_mtime
+            tf.addfile(ti, BytesIO(data))
+            rows.append(f"{sha}  {rel}")
+            count += 1
+        sums = ("\n".join(sorted(rows)) + "\n").encode("utf-8")
+        ti = tarfile.TarInfo(SUMS_NAME)
+        ti.size = len(sums)
+        ti.mtime = time.time()
+        tf.addfile(ti, BytesIO(sums))
+    os.replace(tmp, target)
+    digest = hashlib.sha256(target.read_bytes()).hexdigest()
+    util.write_atomically(Path(str(target) + ".sha256"), f"{digest}  {name}\n")
+    return {"archive": str(target), "records": count,
+            "bytes": target.stat().st_size, "sha256": digest}
+
+
+def _safe_member(name: str) -> bool:
+    if not name or name.startswith("/"):
+        return False
+    parts = Path(name).parts
+    return ".." not in parts
+
+
+def restore(archive: str, yes: bool = False) -> dict:
+    apath = Path(archive).expanduser()
+    if not apath.is_file():
+        util.fail(util.EXIT_USAGE_ERROR, "backup_not_found", {"path": str(apath)})
+    try:
+        tf = tarfile.open(apath, "r:gz")
+    except Exception as exc:
+        util.fail(util.EXIT_USAGE_ERROR, "backup_unreadable", {"error": str(exc)})
+    report: dict[str, Any] = {"archive": str(apath), "dry_run": not yes,
+                              "restored": [], "would_extract": [], "conflicts": [],
+                              "skipped_identical": [], "unsafe": [], "integrity_failed": []}
+    with tf:
+        names = [m.name for m in tf.getmembers() if m.isfile()]
+        sums: dict[str, str] = {}
+        if SUMS_NAME in names:
+            fh = tf.extractfile(SUMS_NAME)
+            if fh:
+                for line in fh.read().decode("utf-8", "replace").splitlines():
+                    if "  " in line:
+                        sha, nm = line.split("  ", 1)
+                        sums[nm] = sha
+        for m in tf.getmembers():
+            if not m.isfile() or m.name == SUMS_NAME:
+                continue
+            if not _safe_member(m.name):
+                report["unsafe"].append(m.name)
+                continue
+            fh = tf.extractfile(m)
+            if fh is None:
+                report["integrity_failed"].append(m.name)
+                continue
+            data = fh.read()
+            want = sums.get(m.name)
+            if want and hashlib.sha256(data).hexdigest() != want:
+                report["integrity_failed"].append(m.name)
+                continue
+            target = util.HOME / m.name
+            if target.is_file():
+                same = False
+                try:
+                    same = target.read_bytes() == data
+                except Exception:
+                    same = False
+                if same:
+                    report["skipped_identical"].append(m.name)
+                    continue
+                if target.stat().st_mtime > m.mtime:
+                    # контент отличается И диск новее — никогда не затираем
+                    report["conflicts"].append({
+                        "path": m.name,
+                        "disk_mtime": util.utc_iso(datetime_from_ts(target.stat().st_mtime)),
+                        "archive_mtime": util.utc_iso(datetime_from_ts(m.mtime)),
+                    })
+                    continue
+            if not yes:
+                report["would_extract"].append(m.name)
+                continue
+            _write_bytes(target, data)
+            report["restored"].append(m.name)
+    return {
+        "archive": report["archive"],
+        "dry_run": report["dry_run"],
+        "restored": len(report["restored"]),
+        "restored_paths": report["restored"],
+        "would_extract": len(report["would_extract"]),
+        "would_extract_paths": report["would_extract"],
+        "conflicts": report["conflicts"],
+        "skipped_identical": len(report["skipped_identical"]),
+        "unsafe": report["unsafe"],
+        "integrity_failed": report["integrity_failed"],
+    }
+
+
+def datetime_from_ts(ts: float):
+    from datetime import datetime, timezone
+    return datetime.fromtimestamp(ts, tz=timezone.utc)
+
+
+def cmd_backup(args) -> None:
+    start = time.time()
+    from . import auditlog
+    profile = util.resolve_profile(args)
+    restore_target = getattr(args, "restore", None)
+    if restore_target:
+        yes = bool(getattr(args, "yes", False))
+        result = restore(restore_target, yes=yes)
+        auditlog.log("backup_restore", profile, str(restore_target),
+                     {"dry_run": result["dry_run"], "restored": result["restored"],
+                      "conflicts": len(result["conflicts"]), "unsafe": len(result["unsafe"])})
+        util.ok(result, elapsed_ms=int((time.time() - start) * 1000))
+    result = create(getattr(args, "dest", None))
+    auditlog.log("backup_create", profile, result["archive"],
+                 {"records": result["records"]})
+    util.ok(result, elapsed_ms=int((time.time() - start) * 1000))

a2a/cards.py

@@ -0,0 +1,58 @@
+"""a2a.cards — P1-7: машинная проверка Agent Cards и gate вызовов.
+
+Канон реализации валидации/правил — bin/validate_cards.py
+один исходный текст; здесь только мост к каталогу cards() внутри A2A_HOME и
+обёртка запрета с аудит-событием (fail-closed).
+"""
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from typing import Any
+
+from . import util
+
+_CANON = Path("bin/validate_cards.py")
+
+
+def _impl():
+    spec = importlib.util.spec_from_file_location("a2a_validate_cards_impl", _CANON)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("validate_cards.py canon not loadable")
+    m = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(m)
+    return m
+
+
+def cards_dir() -> Path:
+    return util.resolve_home() / "cards"
+
+
+def validate_all() -> tuple[bool, dict]:
+    impl = _impl()
+    return impl.validate_dir(cards_dir())
+
+
+def who_can(task_token: str) -> list[dict]:
+    impl = _impl()
+    out = []
+    for f in sorted(cards_dir().glob("*.json")):
+        import json
+        card = json.loads(f.read_text(encoding="utf-8"))
+        caps = [c.lower() for c in card.get("capabilities", [])]
+        if any(task_token.lower() in c for c in caps):
+            out.append({"profile": card["name"], "capabilities": card["capabilities"],
+                        "status": card["status"]})
+    return out
+
+
+def gate_call(caller: str, method: str, target: str, auditlog_mod) -> tuple[bool, str]:
+    """Fail-closed проверка вызова против карточки получателя.
+
+    Отказ пишется в audit log (event=card_denied) — как требует приёмка P1-7.
+    """
+    impl = _impl()
+    allowed, reason = impl.can_call(caller, method, target, cards_dir())
+    if not allowed:
+        auditlog_mod.log("card_denied", caller, target, {"method": method, "reason": reason})
+    return allowed, reason