[TOOLS] Tool Gateway v1: systemd-сервис на 9140, 10 типизированных инструментов (hub.status/notify, ha.states/call, media.queue/recent, calendar.list/create, photos.people/albums), токены акторов owner/family/agent, матрица прав, подтверждения (409) для write, аудит в SQLite. Проверено: статус 74/0, HA 5 светильников, radarr 12 в очереди, создание/удаление события, 403 для agent на ha.call

This commit is contained in:
root committed 2026-11-17 16:07:35 +03:00
1 parent efe0fab66f
commit 623acdc690
2 files changed
+357

No files matched your search

+71
View File
@@ -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 | сервис перезапускается, конфиг читает при старте |
+286
View File
@@ -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 = ('<?xml version="1.0"?><c:calendar-query xmlns:d="DAV:" '
'xmlns:c="urn:ietf:params:xml:ns:caldav"><d:prop><c:calendar-data/></d:prop>'
'<c:filter><c:comp-filter name="VCALENDAR"><c:comp-filter name="VEVENT">'
'<c:time-range start="%s" end="%s"/></c:comp-filter></c:comp-filter></c:filter>'
'</c:calendar-query>' % (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()