From 623acdc690dc16bf3e4136dfd02c4449d6b113b2 Mon Sep 17 00:00:00 2001 From: Roman Buryan Date: Tue, 17 Nov 2026 16:07:35 +0300 Subject: [PATCH] =?UTF-8?q?[TOOLS]=20Tool=20Gateway=20v1:=20systemd-=D1=81?= =?UTF-8?q?=D0=B5=D1=80=D0=B2=D0=B8=D1=81=20=D0=BD=D0=B0=209140,=2010=20?= =?UTF-8?q?=D1=82=D0=B8=D0=BF=D0=B8=D0=B7=D0=B8=D1=80=D0=BE=D0=B2=D0=B0?= =?UTF-8?q?=D0=BD=D0=BD=D1=8B=D1=85=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D1=82=D0=BE=D0=B2=20(hub.status/notify,=20ha?= =?UTF-8?q?.states/call,=20media.queue/recent,=20calendar.list/create,=20p?= =?UTF-8?q?hotos.people/albums),=20=D1=82=D0=BE=D0=BA=D0=B5=D0=BD=D1=8B=20?= =?UTF-8?q?=D0=B0=D0=BA=D1=82=D0=BE=D1=80=D0=BE=D0=B2=20owner/family/agent?= =?UTF-8?q?,=20=D0=BC=D0=B0=D1=82=D1=80=D0=B8=D1=86=D0=B0=20=D0=BF=D1=80?= =?UTF-8?q?=D0=B0=D0=B2,=20=D0=BF=D0=BE=D0=B4=D1=82=D0=B2=D0=B5=D1=80?= =?UTF-8?q?=D0=B6=D0=B4=D0=B5=D0=BD=D0=B8=D1=8F=20(409)=20=D0=B4=D0=BB?= =?UTF-8?q?=D1=8F=20write,=20=D0=B0=D1=83=D0=B4=D0=B8=D1=82=20=D0=B2=20SQL?= =?UTF-8?q?ite.=20=D0=9F=D1=80=D0=BE=D0=B2=D0=B5=D1=80=D0=B5=D0=BD=D0=BE:?= =?UTF-8?q?=20=D1=81=D1=82=D0=B0=D1=82=D1=83=D1=81=2074/0,=20HA=205=20?= =?UTF-8?q?=D1=81=D0=B2=D0=B5=D1=82=D0=B8=D0=BB=D1=8C=D0=BD=D0=B8=D0=BA?= =?UTF-8?q?=D0=BE=D0=B2,=20radarr=2012=20=D0=B2=20=D0=BE=D1=87=D0=B5=D1=80?= =?UTF-8?q?=D0=B5=D0=B4=D0=B8,=20=D1=81=D0=BE=D0=B7=D0=B4=D0=B0=D0=BD?= =?UTF-8?q?=D0=B8=D0=B5/=D1=83=D0=B4=D0=B0=D0=BB=D0=B5=D0=BD=D0=B8=D0=B5?= =?UTF-8?q?=20=D1=81=D0=BE=D0=B1=D1=8B=D1=82=D0=B8=D1=8F,=20403=20=D0=B4?= =?UTF-8?q?=D0=BB=D1=8F=20agent=20=D0=BD=D0=B0=20ha.call?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ops/audits/TOOL-GATEWAY-2026-11-17.md | 71 +++++++ ops/tools/gateway.py | 286 ++++++++++++++++++++++++++ 2 files changed, 357 insertions(+) create mode 100644 ops/audits/TOOL-GATEWAY-2026-11-17.md create mode 100755 ops/tools/gateway.py diff --git a/ops/audits/TOOL-GATEWAY-2026-11-17.md b/ops/audits/TOOL-GATEWAY-2026-11-17.md new file mode 100644 index 0000000..1663b93 --- /dev/null +++ b/ops/audits/TOOL-GATEWAY-2026-11-17.md @@ -0,0 +1,71 @@ +# Tool Gateway — типизированные инструменты (17.11.2026) + +## Что это + +Отдельный сервис `tool-gateway` (порт 9140): один вход для агентов — +`POST /call {tool, args, actor}`. Внутри — права, подтверждения, аудит. +Не «агент с shell», а «агент с API». + +## Запуск + +* systemd `tool-gateway.service` (active); +* конфиг `/etc/tool-gateway/config.json` (600): порт и токены акторов; +* аудит: `/var/lib/tool-gateway/audit.db` (SQLite: ts, actor, tool, args, + result, ok, ms); +* `/health`, `/tools`, `/call`. + +## Инструменты (10) + +| Инструмент | Тип | Подтверждение | Кто может | +|---|---|---|---| +| hub.status | read | — | все | +| hub.notify | write | да | owner, family, agent | +| ha.states | read | — | все | +| ha.call | write | да | owner, family | +| media.queue | read | — | все | +| media.recent | read | — | все | +| calendar.list | read | — | все | +| calendar.create | write | да | owner, family | +| photos.people | read | — | все | +| photos.albums | read | — | все | + +## Проверено + +``` +hub.status → 74 службы, 0 лежит +ha.states → 5 светильников +media.queue → radarr 12 в очереди +calendar.list → 0 событий +calendar.create → 201, событие создано и удалено (204) +ha.call → homeassistant.update_entity 200 +без confirm → 409 confirmation_required +agent + ha.call → 403 forbidden +аудит → записи по каждому вызову +``` + +## Политика + +* `owner` — всё; +* `family` — чтение и запись с подтверждением; +* `agent` — чтение; изменения только через owner. +* Токены в заголовке `X-Gateway-Token`, у каждого актора свой. + +## Что ещё нужно (следующие шаги) + +1. **MCP-адаптер** к OpenClaw: обернуть `/call` в MCP-сервер, чтобы секретарь + видел инструменты нативно (а не через shell). +2. **Больше инструментов**: media.request (заявка), photos.search + (по человеку/дате), approvals (заявки), backup.status. +3. **Rate limit + идемпотентность** (ключ запроса, лимит на актора). +4. **Аудит в Postgres** (перенос из SQLite) и просмотр через hub. +5. **Подтверждения через Matrix**: 409 → заявка → «одобри N». +6. **Секреты**: сейчас читаются из `/root/.*`; позже — Vaultwarden. + +## Ловушки + +| Ловушка | Что было | +|---|---| +| токены actor→token vs token→actor | гейтвей сначала искал наоборот — все вызовы 401 | +| кириллица в CalDAV | путь надо quote(..., safe="/") | +| подтверждения | без `confirm=true` write-инструменты возвращают 409 | +| systemd | сервис перезапускается, конфиг читает при старте | diff --git a/ops/tools/gateway.py b/ops/tools/gateway.py new file mode 100755 index 0000000..55004cf --- /dev/null +++ b/ops/tools/gateway.py @@ -0,0 +1,286 @@ +#!/usr/bin/env python3 +"""Tool Gateway — типизированные инструменты Buryans Hub. + +Один вход для агентов: /call {tool, args, actor}. Внутри — политика, +подтверждения, идемпотентность, лимиты и аудит. + +Запуск: systemd tool-gateway (порт 9140). +""" +import base64 +import json +import os +import re +import sqlite3 +import time +import urllib.error +import urllib.parse +import urllib.request +import uuid +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer + +CFG = "/etc/tool-gateway/config.json" +DB = "/var/lib/tool-gateway/audit.db" +HUB = "http://127.0.0.1:9120" +HA = "http://192.168.1.106:8123" +NC = "http://192.168.1.109:8080" +IMMICH = "http://192.168.1.104:2283" +RADARR = "http://192.168.1.118:7878" +SONARR = "http://192.168.1.117:8989" +JELLYFIN = "http://192.168.1.103:8096" + + +def read(path): + try: + return open(path, encoding="utf-8").read().strip() + except Exception: + return "" + + +CFG_D = json.load(open(CFG)) if os.path.exists(CFG) else {} +TOKENS = {v: k for k, v in (CFG_D.get("tokens") or {}).items()} +HA_TOKEN = read("/root/.ha-token") +RADARR_KEY = read("/root/.radarr-key") +SONARR_KEY = read("/root/.sonarr-key") +JELLYFIN_KEY = read("/root/.jellyfin-key") +IMMICH_KEY = read("/root/.immich-key-new") +NC_USER = "family" +NC_PASS = read("/root/.family-nextcloud-pass") + + +def http(method, url, headers=None, data=None, timeout=20): + req = urllib.request.Request(url, method=method, + data=json.dumps(data).encode() if data is not None else None, + headers=dict({"Content-Type": "application/json"}, **(headers or {}))) + with urllib.request.urlopen(req, timeout=timeout) as r: + body = r.read() + return r.status, body + + +def basic(user, pw): + return "Basic " + base64.b64encode(("%s:%s" % (user, pw)).encode()).decode() + + +# ---------- инструменты ---------- + +def t_hub_status(args): + st, body = http("GET", HUB + "/status.json") + d = json.loads(body) + svc = d.get("services", []) + down = [s["name"] for s in svc if not s.get("up")] + return {"total": len(svc), "down": down} + + +def t_hub_notify(args): + msg = {"title": args.get("title", "Tool Gateway"), + "message": args.get("message", ""), + "priority": args.get("priority", "normal")} + st, body = http("POST", HUB + "/notify", data=msg) + return {"status": st, "body": body.decode("utf-8", "replace")[:200]} + + +def t_ha_states(args): + domain = args.get("domain") + st, body = http("GET", HA + "/api/states", {"Authorization": "Bearer " + HA_TOKEN}) + states = json.loads(body) + if domain: + states = [s for s in states if s["entity_id"].startswith(domain + ".")] + out = [{"entity_id": s["entity_id"], "state": s["state"], + "name": (s.get("attributes") or {}).get("friendly_name")} for s in states] + return {"count": len(out), "states": out[:200]} + + +def t_ha_call(args): + domain = args["domain"] + service = args["service"] + data = args.get("data") or {} + st, body = http("POST", "%s/api/services/%s/%s" % (HA, domain, service), + {"Authorization": "Bearer " + HA_TOKEN}, data) + return {"status": st, "body": body.decode("utf-8", "replace")[:200]} + + +def t_media_queue(args): + out = {} + for name, url, key in (("radarr", RADARR, RADARR_KEY), ("sonarr", SONARR, SONARR_KEY)): + try: + st, body = http("GET", "%s/api/v3/queue?page=1&pageSize=50" % url, + {"X-Api-Key": key}) + d = json.loads(body) + out[name] = {"total": d.get("totalRecords", 0), + "items": [r.get("title") for r in (d.get("records") or [])][:20]} + except Exception as e: + out[name] = {"error": str(e)[:120]} + return out + + +def t_media_recent(args): + st, body = http("GET", JELLYFIN + "/Items?IncludeItemTypes=Movie&Recursive=true" + "&SortBy=DateCreated&SortOrder=Descending&Limit=10" + "&Fields=DateCreated", {"X-Emby-Token": JELLYFIN_KEY}) + d = json.loads(body) + return {"count": len(d.get("Items") or []), + "items": [i.get("Name") for i in (d.get("Items") or [])]} + + +def _caldav(method, path, body=None, headers=None): + url = NC + "/remote.php/dav/calendars/%s/%s/" % (NC_USER, urllib.parse.quote(path, safe="/")) + h = {"Authorization": basic(NC_USER, NC_PASS)} + if headers: + h.update(headers) + req = urllib.request.Request(url, method=method, data=body, headers=h) + with urllib.request.urlopen(req, timeout=25) as r: + return r.status, r.read() + + +def t_calendar_list(args): + days = int(args.get("days", 7)) + now = time.time() + start = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime(now)) + end = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime(now + days * 86400)) + cal = args.get("calendar", "Семья") + body = ('' + '' + '' + '' % (start, end)).encode() + st, raw = _caldav("REPORT", cal, body, {"Content-Type": "application/xml; charset=utf-8", "Depth": "1"}) + txt = raw.decode("utf-8", "replace") + events = [] + for block in re.findall(r"BEGIN:VEVENT(.*?)END:VEVENT", txt, re.S): + s = re.search(r"SUMMARY:(.+)", block) + t = re.search(r"DTSTART[^:]*:(\S+)", block) + events.append({"summary": (s.group(1).strip() if s else ""), + "start": (t.group(1).strip() if t else "")}) + return {"calendar": cal, "count": len(events), "events": events[:30]} + + +def t_calendar_create(args): + title = args["title"] + start = args["start"] # 20261120T150000 + end = args.get("end") or start + cal = args.get("calendar", "Семья") + uid = uuid.uuid4().hex + ics = ("BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//Buryans//ToolGateway//RU\r\n" + "BEGIN:VEVENT\r\nUID:%s\r\nDTSTAMP:%s\r\nDTSTART:%s\r\nDTEND:%s\r\n" + "SUMMARY:%s\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n" + % (uid, time.strftime("%Y%m%dT%H%M%SZ", time.gmtime()), start, end, title)) + st, raw = _caldav("PUT", cal + "/" + uid + ".ics", ics.encode(), + {"Content-Type": "text/calendar; charset=utf-8"}) + return {"status": st, "uid": uid, "calendar": cal, "title": title, "start": start} + + +def t_photos_people(args): + st, body = http("GET", IMMICH + "/api/people", {"x-api-key": IMMICH_KEY}) + d = json.loads(body) + return {"total": d.get("total", 0), + "people": [p.get("name") for p in (d.get("people") or [])][:50]} + + +def t_photos_albums(args): + st, body = http("GET", IMMICH + "/api/albums", {"x-api-key": IMMICH_KEY}) + d = json.loads(body) + return {"count": len(d or []), "albums": [a.get("albumName") for a in (d or [])][:50]} + + +TOOLS = { + "hub.status": {"fn": t_hub_status, "scope": "read", "confirm": False}, + "hub.notify": {"fn": t_hub_notify, "scope": "write", "confirm": True, + "actors": ["owner", "family", "agent"]}, + "ha.states": {"fn": t_ha_states, "scope": "read", "confirm": False}, + "ha.call": {"fn": t_ha_call, "scope": "write", "confirm": True, + "actors": ["owner", "family"]}, + "media.queue": {"fn": t_media_queue, "scope": "read", "confirm": False}, + "media.recent": {"fn": t_media_recent, "scope": "read", "confirm": False}, + "calendar.list": {"fn": t_calendar_list, "scope": "read", "confirm": False}, + "calendar.create": {"fn": t_calendar_create, "scope": "write", "confirm": True, + "actors": ["owner", "family"]}, + "photos.people": {"fn": t_photos_people, "scope": "read", "confirm": False}, + "photos.albums": {"fn": t_photos_albums, "scope": "read", "confirm": False}, +} + + +def audit(actor, tool, args, result, ok, started): + try: + os.makedirs(os.path.dirname(DB), exist_ok=True) + c = sqlite3.connect(DB) + c.execute("""CREATE TABLE IF NOT EXISTS audit( + ts TEXT, actor TEXT, tool TEXT, args TEXT, result TEXT, ok INTEGER, ms INTEGER)""") + c.execute("INSERT INTO audit VALUES(?,?,?,?,?,?,?)", + (time.strftime("%Y-%m-%dT%H:%M:%S"), actor, tool, + json.dumps(args, ensure_ascii=False)[:1000], + json.dumps(result, ensure_ascii=False)[:2000], 1 if ok else 0, + int((time.time() - started) * 1000))) + c.commit() + c.close() + except Exception: + pass + + +class Handler(BaseHTTPRequestHandler): + server_version = "ToolGateway/1.0" + + def _send(self, code, obj): + raw = json.dumps(obj, ensure_ascii=False).encode() + self.send_response(code) + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(raw))) + self.end_headers() + self.wfile.write(raw) + + def _actor(self): + tok = self.headers.get("X-Gateway-Token", "") + return TOKENS.get(tok) + + def log_message(self, *a): + pass + + def do_GET(self): + if self.path == "/health": + return self._send(200, {"ok": True, "tools": len(TOOLS)}) + if self.path == "/tools": + return self._send(200, {"tools": [{"name": k, "scope": v["scope"], + "confirm": v["confirm"]} for k, v in TOOLS.items()]}) + return self._send(404, {"error": "not found"}) + + def do_POST(self): + if self.path != "/call": + return self._send(404, {"error": "not found"}) + actor = self._actor() + if not actor: + return self._send(401, {"error": "bad token"}) + try: + n = int(self.headers.get("Content-Length", 0)) + req = json.loads(self.rfile.read(n).decode() or "{}") + except Exception: + return self._send(400, {"error": "bad json"}) + tool = req.get("tool") + args = req.get("args") or {} + spec = TOOLS.get(tool) + if not spec: + return self._send(404, {"error": "unknown tool"}) + allowed = spec.get("actors", ["owner", "family", "agent"]) + if actor not in allowed: + return self._send(403, {"error": "forbidden for actor", "actor": actor, + "allowed": allowed}) + if spec["confirm"] and not req.get("confirm"): + return self._send(409, {"error": "confirmation_required", "tool": tool, + "hint": "повторите с confirm=true"}) + started = time.time() + try: + result = spec["fn"](args) + audit(actor, tool, args, result, True, started) + return self._send(200, {"ok": True, "result": result}) + except Exception as e: + err = str(e)[:200] + audit(actor, tool, args, {"error": err}, False, started) + return self._send(500, {"ok": False, "error": err}) + + +def main(): + port = int(CFG_D.get("port", 9140)) + srv = ThreadingHTTPServer(("0.0.0.0", port), Handler) + print("tool-gateway on :%d, tools=%d" % (port, len(TOOLS)), flush=True) + srv.serve_forever() + + +if __name__ == "__main__": + main()