From 3f9dd32be584718deefeca6f0e2103c48dabf597 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 11 Oct 2026 02:27:59 +0000 Subject: [PATCH] feat(slack): built-in Slack app over Socket Mode Slack as an adapter of the chat-channel layer (channels.py): a Socket Mode listener in the process holding the lease acknowledges every envelope and queues messages for the channel thread, which answers through bridge.py like Matterbridge and Telegram rooms. A manifest link creates the Slack app in one click; the bot and app-level tokens are sealed settings. Direct messages, mentions, threads, /lens (with clear and compact), voice clips and files are handled. Settings page, docs, changelog and threat model included. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01FKrujJ1UrhR3AD5aSGcgN1 --- CHANGELOG.md | 5 + docs/chat-rooms.md | 22 + fastapi_backend/app/api/v1/routes/admin.py | 17 +- fastapi_backend/app/domain/channels.py | 6 +- fastapi_backend/app/domain/settings.py | 24 +- fastapi_backend/app/domain/slack.py | 462 ++++++++++++++++++ fastapi_backend/app/domain/store.py | 14 + fastapi_backend/app/schemas/admin.py | 15 + fastapi_backend/tests/api/test_slack.py | 201 ++++++++ fastapi_backend/tests/fake_slack.py | 107 ++++ nextjs-frontend/app/openapi-client/index.ts | 7 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 32 ++ .../app/openapi-client/types.gen.ts | 91 ++++ .../components/settings/bodies.tsx | 101 ++++ nextjs-frontend/components/settings/model.ts | 57 +++ .../components/settings/settings-shell.tsx | 2 + nextjs-frontend/openapi.json | 149 ++++++ threat-model.md | 6 +- threat-model.yaml | 2 +- 19 files changed, 1311 insertions(+), 9 deletions(-) create mode 100644 fastapi_backend/app/domain/slack.py create mode 100644 fastapi_backend/tests/api/test_slack.py create mode 100644 fastapi_backend/tests/fake_slack.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 29382e7a0..3db83ef22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **Slack, built in.** Settings › Slack creates a Slack app from Lens's manifest in one click; paste its two tokens + and the assistant answers direct messages, what's said to it in channels and `/lens …`, over Socket Mode: no + Matterbridge, no public address. Voice clips are heard, files are held for the assistant to import, and everything + Matterbridge rooms do works there ([Chat rooms](docs/chat-rooms.md#slack-built-in)). + - **The file tree over NFS.** Settings → NFS share serves the archive's folders and files (namespaces, collections, topics and entities as folders, assets as files) read-only over NFS, to the networks you allow, showing what one chosen account sees. Off until turned on; published on port 12049 of the host ([File shares](docs/file-shares.md)). diff --git a/docs/chat-rooms.md b/docs/chat-rooms.md index 0a90c1cd5..ef0a8cf57 100644 --- a/docs/chat-rooms.md +++ b/docs/chat-rooms.md @@ -26,6 +26,28 @@ Give Lens a bot of its own: a bot that Matterbridge also reads answers neither r Telegram is one adapter of the chat-channel layer (`app/domain/channels.py`) that Matterbridge is another of; a new chat app adds an adapter (reading, sending, files) and gets everything in a room for free. +## Slack, built in + +Slack needs no Matterbridge and no public address either: Lens connects to a Slack app of your own over Socket Mode +and answers there. + +1. Open **Settings → Slack** and click **Create the Slack app**. Slack opens with the app already described (Lens's + manifest: its permissions, the `/lens` command, Socket Mode); pick the workspace and create it. +2. In the app's page, **Install to Workspace**, then copy the **Bot User OAuth Token** (`xoxb-…`, under OAuth & + Permissions). Under **Basic Information → App-Level Tokens**, generate one with `connections:write` and copy it + (`xapp-…`). +3. Paste both tokens in Settings → Slack and turn on **Answer in Slack**. **Check the app** says whether both work. + +Message the app directly (always for Lens), invite it to a channel with `/invite @Lens` and say "Lens, …" or +@mention it, or type `/lens what did we decide about the launch?` anywhere (the answer shows in that channel). +`/lens clear` and `/lens compact` are the [chat commands](assistant.md). In a thread it answers in the thread. Voice +clips are transcribed by the server's speech-to-text and files posted with a message are held for the assistant to +import, as with Telegram. **People it talks to** (Slack usernames or member ids) limits who it answers, and lets them +approve by replying "yes"; **Channels for a namespace's assistant** gives a channel to a namespace (`slack/general = +pods`). Slack is an adapter of the same chat-channel layer as Telegram and Matterbridge (`app/domain/slack.py`). + +Give Lens an app of its own: an app whose bot token Matterbridge also uses answers twice (**Check the app** says so). + ## Set it up in the web app Lens can run Matterbridge for you, so adding Slack or WhatsApp takes no config file: diff --git a/fastapi_backend/app/api/v1/routes/admin.py b/fastapi_backend/app/api/v1/routes/admin.py index 3c9988d32..b5d70d9eb 100644 --- a/fastapi_backend/app/api/v1/routes/admin.py +++ b/fastapi_backend/app/api/v1/routes/admin.py @@ -30,6 +30,7 @@ nfs_share, semantic, settings, + slack, smb_share, sources, speech, @@ -59,6 +60,7 @@ NfsStatus, Removed, SemanticStatus, + SlackStatus, SmbStatus, SpeechTestResult, Started, @@ -89,7 +91,7 @@ def update_settings(section: str, body: dict[str, Any], user: AdminWriter, reque if "*" not in hosts and here not in hosts: raise HTTPException(400, f"that list leaves out {here}, the address you're using, and would lock you out") if ( - section in ("bridge", "telegram") + section in ("bridge", "telegram", "slack") and body.get("enabled") and "account" not in body and not (request.app.state.archive.current().get(section) or {}).get("account") @@ -237,6 +239,19 @@ def test_telegram(user: AdminWriter, cfg: Cfg, db: Db) -> BridgeTestResult: return BridgeTestResult(ok=error is None, error=error) +@router.get("/settings/slack") +def slack_status(user: AdminReader, cfg: Cfg, db: Db) -> SlackStatus: + """How the assistant's Slack app is doing, its slash command, and the link that creates the app from its manifest.""" + return SlackStatus(**slack.status(db, cfg)) + + +@router.post("/settings/slack/test") +def test_slack(user: AdminWriter, cfg: Cfg, db: Db) -> BridgeTestResult: + """Check both Slack tokens, and that the account to answer as exists.""" + error = slack.SLACK.check(db, cfg) + return BridgeTestResult(ok=error is None, error=error) + + @router.post("/settings/documents/node/test") def test_conversion_node(user: AdminWriter, cfg: Cfg) -> ConversionNodeTestResult: """Check that the conversion node (documents.anytopdf_url) answers at its address and takes Lens's token.""" diff --git a/fastapi_backend/app/domain/channels.py b/fastapi_backend/app/domain/channels.py index 07d7ad471..847a5f585 100644 --- a/fastapi_backend/app/domain/channels.py +++ b/fastapi_backend/app/domain/channels.py @@ -4,7 +4,7 @@ An adapter (a Channel) knows only its own connection: whether it's set up (ready), checking it (check), what was said since the last look (fetch), posting a reply (send) and fetching a voice note or file sent with a message (download). Its settings section holds the room settings bridge.py reads: account, name, answer, users, rooms, -approve. Matterbridge (bridge.MATTERBRIDGE) and Telegram (telegram.py) are adapters; each has its own thread, lease +approve. Matterbridge (bridge.MATTERBRIDGE), Telegram (telegram.py) and Slack (slack.py) are adapters; each has its own thread, lease and status, so one being down doesn't stop the other. Messages are dicts in Matterbridge's shape (gateway, channel, account, username, userid, text, event), and may say: @@ -226,9 +226,9 @@ def loop(): def every(): """Every channel Lens has.""" - from . import bridge, telegram + from . import bridge, slack, telegram - return [bridge.MATTERBRIDGE, telegram.TELEGRAM] + return [bridge.MATTERBRIDGE, telegram.TELEGRAM, slack.SLACK] def start_all(db, cfg_fn, stop, base_fn=None, name=None, log_fn=None): diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py index bec3a0f10..2b7c68a44 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -45,6 +45,7 @@ "mail": None, "bridge": None, "telegram": None, + "slack": None, "matterbridge": None, "notifications": None, "telemetry": None, @@ -125,6 +126,7 @@ "mail": ("password",), "bridge": ("token",), "telegram": ("token",), + "slack": ("bot_token", "app_token"), "matterbridge": ("slack_token", "discord_token", "telegram_token", "matrix_password"), "telemetry": ("headers", "prometheus_token"), "fedora": ("password",), @@ -155,6 +157,8 @@ ("telegram", "answer"): {"mention", "all"}, ("telegram", "approve"): {"off", "low_risk"}, ("ai", "injection_check"): {"patterns", "classifier", "model", "off"}, + ("slack", "answer"): {"mention", "all"}, + ("slack", "approve"): {"off", "low_risk"}, ("tunnel", "mode"): {"off", "quick", "token", "managed"}, ("https", "ca"): {"letsencrypt", "zerossl", "both", "custom"}, ("https", "challenge"): {"http", "tls-alpn", "dns"}, @@ -451,6 +455,8 @@ def _check(section, key, value, default): return _bridge_setting(key, value) if section == "telegram" and key not in ("answer", "enabled", "approve"): return _telegram_setting(key, value) + if section == "slack" and key not in ("answer", "enabled", "approve"): + return _slack_setting(key, value) if section == "matterbridge" and key != "run": return _matterbridge_setting(key, value) if (section, key) == ("voice", "tts_base_url"): @@ -720,6 +726,18 @@ def _telegram_setting(key, value): return _bridge_setting(key, value, "telegram") +def _slack_setting(key, value): + prefix = {"bot_token": "xoxb-", "app_token": "xapp-"}.get(key) + if prefix: + value = (value or "").strip() if isinstance(value, str) or value is None else value + if value and not (isinstance(value, str) and value.startswith(prefix) and len(value) <= 500 and " " not in value): + raise ValueError(f"slack.{key} is the Slack app's token starting {prefix}") + return value or None + if key in ("url", "token", "gateway", "poll_seconds"): # Matterbridge's own; Slack keeps a socket open instead + raise ValueError(f"unknown setting slack.{key}") + return _bridge_setting(key, value, "slack") + + def _matterbridge_setting(key, value): if key.endswith(("_channels", "_chats", "_rooms", "_groups")): if not (isinstance(value, list) and len(value) <= 100 and all(isinstance(v, str) and len(v) <= 200 for v in value)): @@ -1155,7 +1173,11 @@ def save(db, base, section, changes, user=None): telemetry.parse_headers(v) # ValueError when malformed if section == "matterbridge" and (len(v) > 500 or "\n" in v.strip()): raise ValueError(f"matterbridge.{k} is one line of text") - if (section, k) in (("documents", "anytopdf_token"), ("telemetry", "prometheus_token"), ("telegram", "token")): + if (section, k) in ( + ("documents", "anytopdf_token"), + ("telemetry", "prometheus_token"), + ("telegram", "token"), + ) or section == "slack": v = _check(section, k, v, None) if (section, k) == ("https", "dns_credentials"): from . import https diff --git a/fastapi_backend/app/domain/slack.py b/fastapi_backend/app/domain/slack.py new file mode 100644 index 000000000..74c3f1a9d --- /dev/null +++ b/fastapi_backend/app/domain/slack.py @@ -0,0 +1,462 @@ +"""The assistant in Slack, through a Slack app of your own over Socket Mode (https://api.slack.com/apis/socket-mode): +no Matterbridge, and no public address. + +Setting it up: Settings › Slack has a link that creates the app from its manifest (manifest()) in one click. Install +it to the workspace and paste two tokens back: the bot token (xoxb-…, from OAuth & Permissions) and an app-level token +with connections:write (xapp-…, from Basic Information). Then invite it to channels with /invite, or message it. + +Everything that happens in a room is bridge.py's, as for the other chat channels (channels.py): it answers as one Lens +account (slack.account), with a conversation per person per channel; a channel can be given to a namespace's +assistant (slack.rooms, "slack/ = namespace"); reversible changes can be approved by replying "yes" +(slack.users); voice clips are transcribed and files are held for the assistant to import. A direct message is always +for Lens; in a channel it answers what names it ("Lens, …" or @mentions the app), or everything with answer "all". +The slash command (/lens , /lens clear, /lens compact) answers in the channel it was typed in. + +The process holding the channel's lease keeps the socket open (Listener) and acknowledges every envelope as it comes +(Slack wants that within 3 seconds); fetch() hands what was said to the channel thread, which answers in order. + +Refine later: Block Kit buttons for approvals, the app's Home tab, streaming an answer by editing the message. +""" + +from __future__ import annotations + +import json +import logging +import queue +import re +import threading +import time +import urllib.error +import urllib.parse +import urllib.request + +from . import auth, channels + +log = logging.getLogger(__name__) +API = "https://slack.com/api" +TIMEOUT = 15 +MAX_CHARS = 3900 # Slack shows up to 4,000 characters of a message's text before cutting it +MAX_DOWNLOAD = 50 * 1024 * 1024 +FILE_HOSTS = ("files.slack.com",) # where the bot token may be sent to fetch a file +RESPONSE_HOSTS = ("hooks.slack.com",) # a slash command's response address +SCOPES = [ + "app_mentions:read", + "channels:history", + "channels:read", + "chat:write", + "commands", + "files:read", + "groups:history", + "groups:read", + "im:history", + "im:read", + "mpim:history", + "mpim:read", + "users:read", +] +EVENTS = ["message.channels", "message.groups", "message.im", "message.mpim"] +AUDIO = ("audio/", "video/mp4", "video/webm", "video/quicktime") # Slack's voice clips are audio or video files + + +class SlackError(channels.ChannelError): + pass + + +def _s(cfg): + return cfg.get("slack") or {} + + +# ---------- the app ---------- +def command(cfg): + """The slash command: /lens, or the assistant's name in lower case.""" + name = re.sub(r"[^a-z0-9_-]+", "-", (_s(cfg).get("name") or "Lens").strip().lower()).strip("-") + return "/" + (name or "lens")[:31] + + +def manifest(cfg): + """The Slack app, as a manifest (https://api.slack.com/reference/manifests): a bot that reads the channels it's + in and its direct messages, with a slash command, over Socket Mode.""" + name = (_s(cfg).get("name") or "Lens").strip()[:35] + return { + "display_information": { + "name": name, + "description": "Lens: intelligence for your agent. Ask about everything Lens knows, with sources.", + }, + "features": { + "app_home": {"messages_tab_enabled": True, "messages_tab_read_only_enabled": False}, + "bot_user": {"display_name": name, "always_online": True}, + "slash_commands": [ + { + "command": command(cfg), + "description": f"Ask {name}", + "usage_hint": "[question] | clear | compact", + "should_escape": False, + } + ], + }, + "oauth_config": {"scopes": {"bot": SCOPES}}, + "settings": { + "event_subscriptions": {"bot_events": EVENTS}, + "interactivity": {"is_enabled": False}, + "org_deploy_enabled": False, + "socket_mode_enabled": True, + "token_rotation_enabled": False, + }, + } + + +def create_url(cfg): + """Where the app is created from its manifest, in one click.""" + return "https://api.slack.com/apps?" + urllib.parse.urlencode({"new_app": 1, "manifest_json": json.dumps(manifest(cfg))}) + + +# ---------- Slack's Web API ---------- +HINTS = { + "invalid_auth": " (check the token)", + "not_authed": " (check the token)", + "not_allowed_token_type": " (the app-level token starts xapp-, the bot token xoxb-)", + "not_in_channel": " (invite the app to the channel: /invite @Lens)", + "missing_scope": " (create the app again from the link in Settings › Slack)", +} + + +def api(token, method, body=None): + """Call a Web API method; its answer, which says ok.""" + req = urllib.request.Request( + f"{API}/{method}", + data=json.dumps(body or {}).encode(), + headers={"Content-Type": "application/json; charset=utf-8", "User-Agent": "Lens", "Authorization": f"Bearer {token}"}, + method="POST", + ) + try: + with urllib.request.urlopen(req, timeout=TIMEOUT) as r: + got = json.loads(r.read() or b"{}") + except urllib.error.HTTPError as e: + raise SlackError(f"Slack answered HTTP {e.code} to {method}") from None + except (urllib.error.URLError, OSError) as e: + raise SlackError(f"can't reach Slack: {getattr(e, 'reason', e)}") from None + except ValueError: + raise SlackError(f"Slack's answer to {method} wasn't JSON") from None + if not got.get("ok"): + err = got.get("error") or "unknown error" + raise SlackError(f"Slack said {err} to {method}{HINTS.get(err, '')}") + return got + + +def respond(url, text): + """Answer a slash command, in the channel it was typed in, through its response address.""" + if urllib.parse.urlsplit(url).hostname not in RESPONSE_HOSTS: + raise SlackError("that isn't a Slack response address") + req = urllib.request.Request( + url, + data=json.dumps({"response_type": "in_channel", "text": text}).encode(), + headers={"Content-Type": "application/json", "User-Agent": "Lens"}, + method="POST", + ) + try: + with urllib.request.urlopen(req, timeout=TIMEOUT): + pass + except (urllib.error.URLError, OSError) as e: + raise SlackError(f"can't answer the slash command: {getattr(e, 'reason', e)}") from None + + +def bot(cfg): + """Who the bot token is: {user_id, user, team, team_id}.""" + return api(_s(cfg)["bot_token"], "auth.test") + + +# ---------- what was said ---------- +class Names: + """Slack ids to names (people and channels), each looked up once.""" + + def __init__(self, token): + self.token, self.people, self.rooms = token, {}, {} + + def person(self, uid): + if uid not in self.people: + try: + u = api(self.token, "users.info", {"user": uid}).get("user") or {} + except SlackError: + return uid + p = u.get("profile") or {} + self.people[uid] = u.get("name") or p.get("display_name") or p.get("real_name") or uid + return self.people[uid] + + def room(self, cid): + if cid not in self.rooms: + try: + c = api(self.token, "conversations.info", {"channel": cid}).get("channel") or {} + except SlackError: + return cid + self.rooms[cid] = "" if c.get("is_im") else c.get("name") or cid + return self.rooms[cid] + + +def plain(text, me, names): + """Slack's markup as plain text, and whether it mentions the bot (`me`): other people's mentions become their + names, channels #name, links their text and address.""" + found = bool(me) and bool(re.search(rf"<@{re.escape(me)}(?:\|[^>]*)?>", text)) + if me: + text = re.sub(rf"\s*<@{re.escape(me)}(?:\|[^>]*)?>[,:]?\s*", " ", text) + text = re.sub(r"<@([A-Z0-9]+)(?:\|([^>]*))?>", lambda m: "@" + (m.group(2) or names.person(m.group(1))), text) + text = re.sub(r"<#[A-Z0-9]+\|([^>]*)>", r"#\1", text) + text = re.sub(r"<(https?://[^|>]+)\|([^>]+)>", r"\2 (\1)", text) + text = re.sub(r"<(https?://[^>]+)>", r"\1", text) + text = re.sub(r"]*)?>", r"@\1", text) + return re.sub(r"\s{2,}", " ", text.replace("<", "<").replace(">", ">").replace("&", "&")).strip(), found + + +def _clip(f): + return bool(f.get("url_private")) and (f.get("subtype") == "slack_audio" or (f.get("mimetype") or "").startswith(AUDIO)) + + +def message(me, team, event, names): + """A Slack message event as a channel message (channels.py), or None for what isn't for anyone (its own or another + bot's, an edit, someone joining).""" + if event.get("type") != "message" or event.get("bot_id") or event.get("subtype") not in (None, "file_share", "thread_broadcast"): + return None + uid, cid = event.get("user"), event.get("channel") + if not uid or uid == me or not cid: + return None + text, mentioned = plain(event.get("text") or "", me, names) + private = event.get("channel_type") == "im" + files = [f for f in event.get("files") or [] if f.get("url_private") and f.get("mode") != "tombstone"] + clip = next((f for f in files if _clip(f)), None) if not text else None # a voice clip with nothing typed + return { + "gateway": "slack", + "channel": "" if private else names.room(cid), + "account": "slack", + "username": names.person(uid), + "userid": uid, + "text": text, + "event": "", + "direct": private or mentioned, + "voice": clip["url_private"] if clip else None, + "files": [ + {"ref": f["url_private"], "filename": f.get("name") or f.get("title") or "file", "size": f.get("size")} + for f in files + if f is not clip + ], + "thread": ["slack", team, cid, uid], + "to": {"channel": cid, "thread": event.get("thread_ts")}, + } + + +def slash(me, team, p, names): + """A slash command as a channel message, always for Lens: /lens what's new; /lens clear and /lens compact [what to + keep] are the chat commands.""" + words = (p.get("text") or "").strip() + first = words.split(" ", 1)[0].lower() + text = "/" + first + words[len(first) :] if first in ("clear", "compact") else plain(words, me, names)[0] + cid, uid = p.get("channel_id") or "", p.get("user_id") or "" + private = p.get("channel_name") == "directmessage" + return { + "gateway": "slack", + "channel": "" if private else (p.get("channel_name") or names.room(cid)), + "account": "slack", + "username": p.get("user_name") or names.person(uid), + "userid": uid, + "text": text or "Hello! What can you do?", + "event": "", + "direct": True, + "voice": None, + "files": [], + "thread": ["slack", team, cid, uid], + "to": {"channel": cid, "response_url": p.get("response_url")}, + } + + +# ---------- the socket ---------- +def _connect(url): # replaced in tests + from websockets.sync.client import connect + + return connect(url, open_timeout=TIMEOUT, close_timeout=2, max_size=2**22) + + +class Listener: + """The Socket Mode connection of this process, while it holds the channel's lease: every envelope acknowledged as + it comes, and the messages in it queued for fetch(). It closes when the tokens change, `stop` is set, or nobody + has fetched for a while (another process took the lease).""" + + IDLE = channels.LEASE_SECONDS + + def __init__(self, cfg): + s = _s(cfg) + self.key = (s.get("bot_token"), s.get("app_token")) + self.todo: queue.Queue = queue.Queue() + self.stop = threading.Event() + self.fetched = time.monotonic() + self.error = None + self.taken = 0 # envelopes read off the socket and dealt with + self.me = bot(cfg) # SlackError when the bot token is wrong: said before anything starts + self.names = Names(s["bot_token"]) + self.thread = threading.Thread(target=self.run, args=(cfg,), daemon=True, name="slack-socket") + self.thread.start() + + def alive(self): + return self.thread.is_alive() + + def take(self, wait=1.0): + """What was said since the last take, waiting up to `wait` seconds for the first.""" + self.fetched = time.monotonic() + out = [] + try: + out.append(self.todo.get(timeout=wait)) + while True: + out.append(self.todo.get_nowait()) + except queue.Empty: + pass + return out + + def envelope(self, ws, env): + """One envelope: acknowledged, and its message queued. False when Slack asks to reconnect.""" + if env.get("type") == "disconnect": + return False + if env.get("envelope_id"): + ws.send(json.dumps({"envelope_id": env["envelope_id"]})) + p, m = env.get("payload") or {}, None + me, team = self.me.get("user_id"), self.me.get("team_id") + if env.get("type") == "events_api": + m = message(me, team, p.get("event") or {}, self.names) + elif env.get("type") == "slash_commands": + m = slash(me, team, p, self.names) + if m: + self.todo.put(m) + self.taken += 1 + return True + + def run(self, cfg): + pause = 1 + while not self.stop.is_set() and time.monotonic() - self.fetched < self.IDLE: + try: + url = api(_s(cfg)["app_token"], "apps.connections.open")["url"] + with _connect(url) as ws: + self.error, pause = None, 1 + while not self.stop.is_set() and time.monotonic() - self.fetched < self.IDLE: + try: + raw = ws.recv(timeout=1) + except TimeoutError: + continue + try: + env = json.loads(raw) + except ValueError: + continue + if not self.envelope(ws, env): + break + except Exception as e: # noqa: BLE001 - said in the status; tried again, waiting longer each time + self.error = str(e) + log.warning("slack: %s", e) + self.stop.wait(pause) + pause = min(60, pause * 2) + + +_LISTENERS: dict = {} # the channel's Listener in this process +_LOCK = threading.Lock() + + +def listener(cfg): + """This process's Listener for the current tokens, started (again) when needed.""" + s = _s(cfg) + with _LOCK: + old = _LISTENERS.get("socket") + if old and old.alive() and old.key == (s.get("bot_token"), s.get("app_token")): + return old + if old: + old.stop.set() + _LISTENERS["socket"] = Listener(cfg) + return _LISTENERS["socket"] + + +class _SlackOnly(urllib.request.HTTPRedirectHandler): + """Redirects followed only within Slack's file hosts: urllib carries the Authorization header along.""" + + def redirect_request(self, req, fp, code, msg, headers, newurl): + if urllib.parse.urlsplit(newurl).hostname not in FILE_HOSTS: + raise SlackError("Slack sent the file somewhere else; download it in Slack and upload it in the web app") + return super().redirect_request(req, fp, code, msg, headers, newurl) + + +# ---------- the channel ---------- +class Slack(channels.Channel): + key, label, lease = "slack", "Slack", "slack" + + def ready(self, cfg): + s = _s(cfg) + if not s.get("enabled"): + return "off" + if not s.get("bot_token"): + return "the app's bot token (xoxb-…)" + if not s.get("app_token"): + return "the app-level token (xapp-…)" + if not s.get("account"): + return "a Lens account to answer as" + return None + + def check(self, db, cfg): + s = _s(cfg) + if not s.get("bot_token") or not s.get("app_token"): + return "paste both tokens first: the bot token (xoxb-…) and the app-level token (xapp-…)" + mb = cfg.get("matterbridge") or {} + if mb.get("run") and mb.get("slack_token") == s["bot_token"]: + return "Matterbridge uses this Slack app too; give Lens an app of its own, or take it out of Matterbridge" + try: + bot(cfg) + api(s["app_token"], "apps.connections.open") + except SlackError as e: + return str(e) + if not s.get("account"): + return "choose the Lens account it answers as" + u = auth.find_account(db, s["account"]) + if not u or u.get("disabled"): + return f"there's no active Lens account {s['account']}" + return None + + def fetch(self, db, cfg): + lst = listener(cfg) + got = lst.take() + channels.keep(db, self, team=lst.me.get("team"), bot=lst.me.get("user")) + if lst.error and not got: + raise SlackError(lst.error) + return got + + def send(self, cfg, m, text): + text = text or "(no answer)" + to = m.get("to") or {} + for i in range(0, len(text), MAX_CHARS): + part = text[i : i + MAX_CHARS] + if to.get("response_url"): + respond(to["response_url"], part) + continue + body = {"channel": to["channel"], "text": part, "unfurl_links": False, "unfurl_media": False} + if to.get("thread"): + body["thread_ts"] = to["thread"] + api(_s(cfg)["bot_token"], "chat.postMessage", body) + + def download(self, cfg, ref): + if urllib.parse.urlsplit(ref).hostname not in FILE_HOSTS: # the bot token goes only to Slack + raise SlackError("that isn't a Slack file address") + req = urllib.request.Request(ref, headers={"Authorization": f"Bearer {_s(cfg)['bot_token']}", "User-Agent": "Lens"}) + try: + with urllib.request.build_opener(_SlackOnly).open(req, timeout=60) as r: + data = r.read(MAX_DOWNLOAD + 1) + except (urllib.error.URLError, OSError) as e: + raise SlackError(f"couldn't fetch the file from Slack: {getattr(e, 'reason', e)}") from None + if len(data) > MAX_DOWNLOAD: + raise SlackError("that file is over 50 MB; upload it in the web app instead") + return data + + def pause(self, cfg, reading, failed): + if failed: + return 5 + return 0 if reading else 2 # reading: take() did the waiting + + +SLACK = Slack() + + +def status(db, cfg): + """channels.status, with the workspace and bot it's connected as, the slash command and the link that creates the + app.""" + s = channels.status(db, cfg, SLACK) + k = channels.state(db, SLACK) + return {**s, "team": k.get("team"), "bot": k.get("bot"), "command": command(cfg), "create_url": create_url(cfg)} diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 90dcf8397..318813a3a 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -394,6 +394,20 @@ def labels(): # a Bot API server of your own (telegram-bot-api), else Telegram's "api_url": None, }, + # Slack through an app of your own over Socket Mode (slack.py), made from the manifest in Settings › Slack: + # bot_token is its xoxb- token, app_token its app-level xapp- token (connections:write); the room settings are + # bridge's: account, name, answer, users (Slack usernames or ids), rooms ("slack/ = namespace"), approve + "slack": { + "enabled": False, + "bot_token": None, + "app_token": None, + "account": None, + "name": "Lens", + "answer": "mention", + "users": [], + "rooms": [], + "approve": "low_risk", + }, # Matterbridge run by Lens (matterbridge.py): with `run` on, the matterbridge service in Docker Compose gets its # config from these, a gateway per room, and the bridge talks to it; off, bridge.url is a Matterbridge of your own "matterbridge": { diff --git a/fastapi_backend/app/schemas/admin.py b/fastapi_backend/app/schemas/admin.py index 363c71b7d..c70c9f0a6 100644 --- a/fastapi_backend/app/schemas/admin.py +++ b/fastapi_backend/app/schemas/admin.py @@ -59,6 +59,21 @@ class SmbStatus(ResponseModel): mount: str = Field(description="the command that mounts it on Linux") +class SlackStatus(ResponseModel): + state: Literal["off", "incomplete", "starting", "running", "error"] = Field( + description="off; incomplete (`error` says what's missing); starting (no server process has connected yet); " + "running; error (the connection or the last message failed, `error` says why)" + ) + error: str | None = None + holder: str | None = Field(None, description="the server process connected to Slack") + at: str | None = Field(None, description="when it last heard from Slack") + answered: int | None = Field(None, description="messages it answered") + team: str | None = Field(None, description="the Slack workspace it's connected to") + bot: str | None = Field(None, description="the app's bot user") + command: str = Field(description="the slash command, such as /lens") + create_url: str = Field(description="where the Slack app is created from its manifest, in one click") + + class TunnelStatus(ResponseModel): mode: Literal["off", "quick", "token", "managed"] running: bool = Field(description="cloudflared is running in a server process") diff --git a/fastapi_backend/tests/api/test_slack.py b/fastapi_backend/tests/api/test_slack.py new file mode 100644 index 000000000..2a01fe33b --- /dev/null +++ b/fastapi_backend/tests/api/test_slack.py @@ -0,0 +1,201 @@ +"""The assistant in Slack through an app of Lens's own over Socket Mode: made from a manifest in one click, set up in +the app with its two tokens, it acknowledges every envelope, answers direct messages, what's said to it in channels +and its slash command, as the account it was given, hears voice clips and holds files for the assistant to import.""" + +from __future__ import annotations + +import json +import time +import urllib.parse + +import pytest + +from app.domain import channels, settings, slack, voice +from tests import fake_llm, fake_slack +from tests.api._assist import start_llm +from tests.helpers import login, make_user, seed + +event, command = fake_slack.event, fake_slack.command + + +@pytest.fixture +def sl(monkeypatch): + srv, url = fake_slack.start() + sock = fake_slack.Socket() + monkeypatch.setattr(slack, "API", url + "/api") + monkeypatch.setattr(slack, "FILE_HOSTS", ("127.0.0.1",)) + monkeypatch.setattr(slack, "RESPONSE_HOSTS", ("127.0.0.1",)) + monkeypatch.setattr(slack, "_connect", lambda u: sock) + fake_slack.Handler.url, fake_slack.Handler.socket = url, sock + yield fake_slack.Handler + for lst in slack._LISTENERS.values(): + lst.stop.set() + slack._LISTENERS.clear() + srv.shutdown() + + +@pytest.fixture +def llm(cfg): + srv = start_llm(cfg) + yield fake_llm.Handler + srv.shutdown() + + +@pytest.fixture +def app(cfg, db, llm): + from app.main import create_app + + return create_app(cfg, db, background=False) + + +@pytest.fixture +def ws(app, db, cfg, folder, sl): + """Seeded recordings, a viewer of pods to answer as, and the Slack app set up for them.""" + seed(db, cfg, folder) + make_user(db, "root@x.io", "root password 1", admin=True) + make_user(db, "bot@x.io", "bot password 1", roles={"pods": "viewer"}) + cfg["slack"] = {**cfg["slack"], "enabled": True, "bot_token": fake_slack.BOT, "app_token": fake_slack.APP, "account": "bot@x.io"} + cfg["ai"]["tools"] = False + return sl + + +def said(db, cfg, h, *envelopes, me="api-1"): + """Hand the envelopes to Lens over the socket, and look until each is acknowledged and answered: how many were.""" + lst = slack._LISTENERS.get("socket") + want = (lst.taken if lst else 0) + len(envelopes) + for e in envelopes: + h.socket.envelopes.put(e) + n, until = 0, time.monotonic() + 10 + while time.monotonic() < until: + n += channels.tick(db, cfg, cfg, me, slack.SLACK) + lst = slack._LISTENERS.get("socket") + if lst and lst.taken >= want and lst.todo.empty(): + return n + raise AssertionError("Lens didn't take every envelope") + + +def acked(h): + return [s["envelope_id"] for s in h.socket.sent] + + +def test_the_app_is_made_from_a_manifest_in_one_click(cfg): + m = slack.manifest(cfg) + assert m["settings"]["socket_mode_enabled"] is True # no public address + assert m["features"]["slash_commands"][0]["command"] == "/lens" + assert {"chat:write", "commands", "im:history", "channels:history", "files:read"} <= set(m["oauth_config"]["scopes"]["bot"]) + url = urllib.parse.urlsplit(slack.create_url(cfg)) + assert url.netloc == "api.slack.com" and json.loads(urllib.parse.parse_qs(url.query)["manifest_json"][0]) == m + cfg["slack"]["name"] = "Pod Bot" + assert slack.command(cfg) == "/pod-bot" and slack.manifest(cfg)["features"]["bot_user"]["display_name"] == "Pod Bot" + + +def test_slack_is_set_up_and_checked_in_the_app(client, db, cfg, sl): + make_user(db, "root@x.io", "root password 1", admin=True) + a = login(client, "root@x.io", "root password 1") + got = client.get("/api/v1/settings/slack", headers=a).json() + assert got["state"] == "off" and got["command"] == "/lens" and got["create_url"].startswith("https://api.slack.com/apps?new_app=1") + assert "paste both tokens" in client.post("/api/v1/settings/slack/test", headers=a).json()["error"] + assert client.put("/api/v1/settings/slack", headers=a, json={"bot_token": "xapp-1"}).status_code == 400 + r = client.put("/api/v1/settings/slack", headers=a, json={"bot_token": " xoxb-test ", "app_token": "xapp-wrong", "enabled": True}) + assert r.status_code == 200, r.text + saved = settings.Settings(db, cfg).current()["slack"] + assert saved["bot_token"] == "xoxb-test" and saved["account"] == "root@x.io" # who turned it on is who it answers as + assert "xapp-wrong" not in client.get("/api/v1/settings", headers=a).text # the tokens are secrets + err = client.post("/api/v1/settings/slack/test", headers=a).json()["error"] + assert "invalid_auth" in err and "apps.connections.open" in err + client.put("/api/v1/settings/slack", headers=a, json={"app_token": fake_slack.APP}) + assert client.post("/api/v1/settings/slack/test", headers=a).json() == {"ok": True, "error": None} + assert client.get("/api/v1/settings/slack", headers=a).json()["state"] == "starting" + r = client.put("/api/v1/settings/slack", headers=a, json={"users": ["@alice", " ", "U2"], "rooms": ["slack/general = Pods"]}) + assert r.status_code == 200, r.text + saved = settings.Settings(db, cfg).current()["slack"] + assert saved["users"] == ["alice", "U2"] and saved["rooms"] == ["slack/general = pods"] + for bad in ({"account": "bot"}, {"answer": "sometimes"}, {"approve": "always"}, {"poll_seconds": 2}, {"app_token": "xoxb-1"}): + assert client.put("/api/v1/settings/slack", headers=a, json=bad).status_code == 400, bad + + +def test_matterbridge_using_the_same_app_is_caught(db, cfg, ws): + cfg["matterbridge"].update(run=True, slack_token=fake_slack.BOT) + assert "Matterbridge uses this Slack app too" in slack.SLACK.check(db, cfg) + cfg["matterbridge"].update(run=False) + assert slack.SLACK.check(db, cfg) is None + + +def test_it_answers_direct_messages_mentions_and_the_slash_command(db, cfg, ws, llm): + n = said( + db, + cfg, + ws, + {"type": "hello"}, + event("what leaves on Friday?", channel="D1", channel_type="im"), # a direct message: always for Lens + event("lunch anyone?", user="U2"), + event("<@UBOT> when does the shipment leave? ", user="U2", thread_ts="5.0"), + event("Lens, hello", user="U3"), + event("I said that", bot_id="B9"), # another bot + event("edited", subtype="message_changed"), + command("who hosts <@U3|carol>'s show?", response_url=ws.url + "/commands/1"), + ) + assert n == 4 and len(acked(ws)) == 7 # every envelope acknowledged, answered or not + assert [p["channel"] for p in ws.posted] == ["D1", "C1", "C1"] and all(p["text"] == "OK" for p in ws.posted) + assert ws.posted[1]["thread_ts"] == "5.0" and "thread_ts" not in ws.posted[0] # a thread is answered in the thread + assert ws.responses == [{"response_type": "in_channel", "text": "OK"}] # the slash command, where it was typed + asked = [m["messages"][-1]["content"] for m in llm.seen if m.get("messages")] + assert any(c.endswith("Question: what leaves on Friday?") for c in asked) + assert any(c.endswith("Question: when does the shipment leave? the plan (https://x.io)") for c in asked) + assert any(c.endswith("Question: who hosts @carol's show?") for c in asked) + titles = db.rows("SELECT VALUE title FROM chat WHERE kind = 'bridge' ORDER BY title") + assert titles == ["Slack · alice", "Slack · general · bob", "Slack · general · carol"] + s = slack.status(db, cfg) + assert s["state"] == "running" and s["answered"] == 4 and (s["team"], s["bot"]) == ("Acme", "lens") + + +def test_the_slash_command_carries_the_chat_commands(sl): + names = slack.Names(fake_slack.BOT) + p = command("compact keep the dates")["payload"] + assert slack.slash("UBOT", "T1", p, names)["text"] == "/compact keep the dates" # bridge.py does /clear and /compact + assert slack.slash("UBOT", "T1", {**p, "text": "Clear"}, names)["text"] == "/clear" + assert slack.slash("UBOT", "T1", {**p, "text": ""}, names)["text"] == "Hello! What can you do?" + + +def test_chat_commands_through_the_slash_command(db, cfg, ws, llm): + said(db, cfg, ws, event("what leaves on Friday?", channel="D1", channel_type="im")) + asked = len(llm.seen) + clear = command("clear", user="U1", user_name="alice", channel="D1", channel_name="directmessage", response_url=ws.url + "/commands/2") + assert said(db, cfg, ws, clear) == 1 + assert len(ws.responses) == 1 and ws.responses[0]["text"] != "OK" and len(llm.seen) == asked # done by Lens, no model + + +def test_who_may_talk_to_it_and_rooms_given_to_a_namespace(db, cfg, ws, llm): + cfg["slack"]["users"] = ["alice"] + assert said(db, cfg, ws, event("Lens, hi", user="U2")) == 0 # bob isn't let in + cfg["slack"]["rooms"] = ["slack/general = pods"] + assert said(db, cfg, ws, event("<@UBOT> when do episodes ship?", user="U1")) == 1 + assert db.one("SELECT VALUE scope FROM chat WHERE kind = 'bridge' LIMIT 1") == {"namespaces": ["pods"]} + + +def test_voice_clips_are_heard_and_files_held(db, cfg, ws, llm, monkeypatch): + ws.files["clip.webm"] = b"webm..." + ws.files["notes.txt"] = b"Episode notes.\n" + heard = [] + monkeypatch.setattr(voice, "can_transcribe", lambda cfg: "sensevoice") + monkeypatch.setattr(voice, "transcribe", lambda cfg, data: heard.append(data) or {"text": "what leaves on Friday?"}) + clip = {"name": "clip.webm", "mimetype": "audio/webm", "subtype": "slack_audio", "url_private": ws.url + "/files/clip.webm"} + assert said(db, cfg, ws, event("", channel="D1", channel_type="im", subtype="file_share", files=[clip])) == 1 + assert heard == [b"webm..."] and ws.posted[-1]["text"] == "(Heard: “what leaves on Friday?”)\n\nOK" + doc = {"name": "notes.txt", "mimetype": "text/plain", "size": 15, "url_private": ws.url + "/files/notes.txt"} + assert said(db, cfg, ws, event("file this in pods", channel="D1", channel_type="im", subtype="file_share", files=[doc])) == 1 + held = db.rows("SELECT * FROM upload WHERE state = 'held'") + assert len(held) == 1 and held[0]["filename"] == "notes.txt" and held[0]["email"] == "bot@x.io" + with pytest.raises(slack.SlackError): # the bot token goes only to Slack's file hosts + slack.SLACK.download(cfg, "https://evil.example/notes.txt") + + +def test_one_process_listens_and_long_answers_are_split(db, cfg, ws, llm): + assert said(db, cfg, ws, event("hi", channel="D1", channel_type="im"), me="api-1") == 1 + assert channels.tick(db, cfg, cfg, "worker-2", slack.SLACK) == 0 # api-1 holds it + slack.SLACK.send(cfg, {"to": {"channel": "C1"}}, "y" * 9000) + assert [len(p["text"]) for p in ws.posted[-3:]] == [3900, 3900, 1200] + cfg["slack"]["bot_token"] = "xoxb-wrong" # a new token: a new connection, and the error said + with pytest.raises(slack.SlackError): + channels.tick(db, cfg, cfg, "api-1", slack.SLACK) + assert "invalid_auth" in slack.status(db, cfg)["error"] diff --git a/fastapi_backend/tests/fake_slack.py b/fastapi_backend/tests/fake_slack.py new file mode 100644 index 000000000..ff17bc4ec --- /dev/null +++ b/fastapi_backend/tests/fake_slack.py @@ -0,0 +1,107 @@ +"""A tiny stand-in for Slack: its Web API (the methods Lens calls; what's posted lands in `posted`), files to fetch with +the bot token (`files`), slash-command response addresses (what's sent lands in `responses`), and a Socket Mode +connection (Socket) that hands out envelopes and keeps what Lens sends back, its acknowledgements.""" + +import http.server +import json +import queue +import threading + +BOT = "xoxb-test" +APP = "xapp-test" + + +class Handler(http.server.BaseHTTPRequestHandler): + posted: list = [] + responses: list = [] + files: dict = {} + people = {"U1": "alice", "U2": "bob", "U3": "carol"} + rooms = {"C1": "general", "D1": None} + + def log_message(self, *a): + pass + + def _send(self, obj, status=200, ctype="application/json"): + data = obj if isinstance(obj, bytes) else json.dumps(obj).encode() + self.send_response(status) + self.send_header("Content-Type", ctype) + self.send_header("Content-Length", str(len(data))) + self.end_headers() + self.wfile.write(data) + + def do_GET(self): + name = self.path.rsplit("/", 1)[-1] + if self.headers.get("Authorization") != f"Bearer {BOT}" or name not in Handler.files: + return self._send(b"no", 404, "text/plain") + self._send(Handler.files[name], ctype="application/octet-stream") + + def do_POST(self): + body = json.loads(self.rfile.read(int(self.headers.get("Content-Length") or 0)) or b"{}") + method = self.path.rsplit("/", 1)[-1] + auth = self.headers.get("Authorization") + if self.path.startswith("/commands/"): + Handler.responses.append(body) + return self._send(b"ok", ctype="text/plain") + if method == "apps.connections.open": + if auth != f"Bearer {APP}": + return self._send({"ok": False, "error": "invalid_auth"}) + return self._send({"ok": True, "url": "wss://fake.slack/link"}) + if auth != f"Bearer {BOT}": + return self._send({"ok": False, "error": "invalid_auth"}) + if method == "auth.test": + return self._send({"ok": True, "user_id": "UBOT", "user": "lens", "team": "Acme", "team_id": "T1"}) + if method == "users.info": + return self._send({"ok": True, "user": {"name": Handler.people.get(body["user"], body["user"]), "profile": {}}}) + if method == "conversations.info": + name = Handler.rooms.get(body["channel"], body["channel"]) + return self._send({"ok": True, "channel": {"name": name, "is_im": name is None}}) + if method == "chat.postMessage": + Handler.posted.append(body) + return self._send({"ok": True}) + self._send({"ok": False, "error": "unknown_method"}) + + +def start(): + Handler.posted, Handler.responses, Handler.files = [], [], {} + srv = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler) + threading.Thread(target=srv.serve_forever, daemon=True).start() + return srv, f"http://127.0.0.1:{srv.server_address[1]}" + + +class Socket: + """The Socket Mode connection: recv() hands out what's put in `envelopes` (else times out), send() keeps what Lens + sends.""" + + def __init__(self): + self.envelopes: queue.Queue = queue.Queue() + self.sent: list = [] + + def __enter__(self): + return self + + def __exit__(self, *a): + pass + + def recv(self, timeout=None): + try: + return json.dumps(self.envelopes.get(timeout=timeout)) + except queue.Empty: + raise TimeoutError from None + + def send(self, data): + self.sent.append(json.loads(data)) + + +_n = [0] + + +def event(text="", user="U1", channel="C1", channel_type="channel", **kw): + _n[0] += 1 + ev = {"type": "message", "text": text, "user": user, "channel": channel, "channel_type": channel_type, "ts": f"{_n[0]}.0", **kw} + return {"envelope_id": f"env-{_n[0]}", "type": "events_api", "payload": {"team_id": "T1", "event": ev}} + + +def command(text, user="U2", user_name="bob", channel="C1", channel_name="general", response_url="http://hooks/commands/1"): + _n[0] += 1 + p = {"command": "/lens", "text": text, "user_id": user, "user_name": user_name, "channel_id": channel, "channel_name": channel_name} + return {"envelope_id": f"env-{_n[0]}", "type": "slash_commands", "payload": {**p, "response_url": response_url}} diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index fe386c737..812a243b5 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -2653,6 +2653,10 @@ export type { SkipTopicCandidateErrors, SkipTopicCandidateResponse, SkipTopicCandidateResponses, + SlackStatus, + SlackStatusData, + SlackStatusResponse, + SlackStatusResponses, SmbStatus, SmbStatusData, SmbStatusResponse, @@ -2798,6 +2802,9 @@ export type { TestNotifyTargetErrors, TestNotifyTargetResponse, TestNotifyTargetResponses, + TestSlackData, + TestSlackResponse, + TestSlackResponses, TestSourceData, TestSourceError, TestSourceErrors, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 65f89dc11..079b96fbe 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -1293,6 +1293,8 @@ import type { SkipTopicCandidateData, SkipTopicCandidateErrors, SkipTopicCandidateResponses, + SlackStatusData, + SlackStatusResponses, SmbStatusData, SmbStatusResponses, SpeakTextData, @@ -1352,6 +1354,8 @@ import type { TestNotifyTargetData, TestNotifyTargetErrors, TestNotifyTargetResponses, + TestSlackData, + TestSlackResponses, TestSourceData, TestSourceErrors, TestSourceResponses, @@ -2691,6 +2695,34 @@ export class Admin { }); } + /** + * Slack Status + * + * How the assistant's Slack app is doing, its slash command, and the link that creates the app from its manifest. + */ + public static slackStatus( + options?: Options, + ): RequestResult { + return (options?.client ?? client).get({ + url: "/api/v1/settings/slack", + ...options, + }); + } + + /** + * Test Slack + * + * Check both Slack tokens, and that the account to answer as exists. + */ + public static testSlack( + options?: Options, + ): RequestResult { + return (options?.client ?? client).post({ + url: "/api/v1/settings/slack/test", + ...options, + }); + } + /** * Test Conversion Node * diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 1f0780b3a..c2e20f2b2 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -15671,6 +15671,65 @@ export type SimilarTopic = { [key: string]: unknown; }; +/** + * SlackStatus + */ +export type SlackStatus = { + /** + * State + * + * off; incomplete (`error` says what's missing); starting (no server process has connected yet); running; error (the connection or the last message failed, `error` says why) + */ + state: "off" | "incomplete" | "starting" | "running" | "error"; + /** + * Error + */ + error?: string | null; + /** + * Holder + * + * the server process connected to Slack + */ + holder?: string | null; + /** + * At + * + * when it last heard from Slack + */ + at?: string | null; + /** + * Answered + * + * messages it answered + */ + answered?: number | null; + /** + * Team + * + * the Slack workspace it's connected to + */ + team?: string | null; + /** + * Bot + * + * the app's bot user + */ + bot?: string | null; + /** + * Command + * + * the slash command, such as /lens + */ + command: string; + /** + * Create Url + * + * where the Slack app is created from its manifest, in one click + */ + create_url: string; + [key: string]: unknown; +}; + /** * SmbStatus */ @@ -20860,6 +20919,38 @@ export type TestTelegramResponses = { export type TestTelegramResponse = TestTelegramResponses[keyof TestTelegramResponses]; +export type SlackStatusData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/settings/slack"; +}; + +export type SlackStatusResponses = { + /** + * Successful Response + */ + 200: SlackStatus; +}; + +export type SlackStatusResponse = SlackStatusResponses[keyof SlackStatusResponses]; + +export type TestSlackData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/settings/slack/test"; +}; + +export type TestSlackResponses = { + /** + * Successful Response + */ + 200: BridgeTestResult; +}; + +export type TestSlackResponse = TestSlackResponses[keyof TestSlackResponses]; + export type TestConversionNodeData = { body?: never; path?: never; diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx index 3eea0db2b..b465792b2 100644 --- a/nextjs-frontend/components/settings/bodies.tsx +++ b/nextjs-frontend/components/settings/bodies.tsx @@ -318,6 +318,8 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) { return ; case "telegram": return ; + case "slack": + return ; case "remote-access": return ; case "components": @@ -1528,6 +1530,105 @@ function TelegramBody({ ctx }: { ctx: BodyCtx }) { ); } +function SlackToken({ ctx, id, label }: { ctx: BodyCtx; id: "bot_token" | "app_token"; label: string }) { + const sl = ctx.view.slack; + const st = ctx.state(`slack.${id}`); + return ( + st.onChange(x)} + /> + ); +} + +function SlackBody({ ctx }: { ctx: BodyCtx }) { + const client = useApiClient(); + const sl = ctx.view.slack; + const status = useQuery({ + queryKey: ["slack-status", sl?.updated_at ?? null], + queryFn: () => data(Admin.slackStatus({ client })), + refetchInterval: 10_000, + }); + const test = useMutation({ mutationFn: () => data(Admin.testSlack({ client })) }); + const s = status.data; + return ( + <> + {s?.state === "running" ? ( + + {s.answered ? `Answered ${s.answered} message${s.answered === 1 ? "" : "s"} so far. ` : ""} + Message {s.bot ? `@${s.bot}` : "the app"}, invite it to a channel with /invite, or type {s.command}. Each + person’s conversation is in Chat for the account it answers as. + + ) : s?.state === "error" ? ( + + {s.error} + + ) : s?.state === "incomplete" ? ( + + It needs {s.error}. + + ) : s?.state === "starting" ? ( + A server process connects to Slack within a few seconds. + ) : ( + + + Create the Slack app + {" "} + (one click: it’s made from Lens’s manifest), install it to your workspace, then paste its two tokens below and + turn this on. + + )} + + + + {s?.create_url && s.state !== "off" && ( +

+ + Create the Slack app again + {" "} + from Lens’s manifest, for another workspace or to get new permissions. +

+ )} + +
+ + +
+ + + +
+ + {ctx.dirty && ( + Uses the saved settings, not your unsaved changes + )} +
+ {test.data && + (test.data.ok ? ( + + Both tokens and the account it answers as check out. + + ) : ( + + {test.data.error} + + ))} + {test.isError && {test.error.message}} + + ); +} + function MatterbridgeSecret({ ctx, id, label }: { ctx: BodyCtx; id: string; label: string }) { const m = ctx.view.matterbridge; const st = ctx.state(`matterbridge.${id}`); diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index 106c8ebee..21161b838 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -82,6 +82,7 @@ export type SectionId = | "mail" | "bridge" | "telegram" + | "slack" | "telemetry" | "fedora" | "sensors" @@ -245,6 +246,13 @@ export const SECTIONS: SectionSpec[] = [ description: "The assistant in Telegram through a bot of your own: paste its token from @BotFather. No Matterbridge and no public address needed.", }, + { + id: "slack", + label: "Slack", + backend: ["slack"], + description: + "The assistant in Slack through an app of your own, created in one click: direct messages, channels and /lens. No Matterbridge and no public address needed.", + }, { id: "notifications", label: "Notifications", @@ -1109,6 +1117,55 @@ export const FIELDS: FieldSpec[] = [ placeholder: "https://api.telegram.org", hint: "Leave empty unless you run your own telegram-bot-api server.", }, + // Slack (slack.py) + { section: "slack", key: "enabled", label: "Answer in Slack", kind: "switch" }, + { + section: "slack", + key: "account", + label: "Answers as", + kind: "text", + nullable: true, + placeholder: "you, when left empty", + hint: "The Lens account it answers as: it reads what that account can read, and changes wait for approval.", + }, + { section: "slack", key: "name", label: "Its name in channels", kind: "text" }, + { + section: "slack", + key: "answer", + label: "In channels, answers", + kind: "select", + options: [ + { value: "mention", label: "Messages that name it or @mention the app" }, + { value: "all", label: "Every message in the channels it’s in" }, + ], + }, + { + section: "slack", + key: "users", + label: "People it talks to", + kind: "lines", + mono: true, + hint: "Slack usernames or member ids, one per line; empty answers everyone in the workspace.", + }, + { + section: "slack", + key: "approve", + label: "Approving in Slack", + kind: "select", + options: [ + { value: "low_risk", label: "Entity merges and edits, new namespaces" }, + { value: "off", label: "Only in the web app" }, + ], + hint: "The people above can reply “yes” or “no” to these in Slack (only when the list isn’t empty). Settings, imports, runs and extensions are always approved in the web app.", + }, + { + section: "slack", + key: "rooms", + label: "Channels for a namespace’s assistant", + kind: "lines", + mono: true, + hint: "One per line, like slack/general = pods: conversations there talk to that namespace’s own assistant. Elsewhere Lens picks the namespace for each question.", + }, // Matterbridge run by Lens (Chat rooms) { section: "matterbridge", key: "run", label: "Run Matterbridge here", kind: "switch" }, { section: "matterbridge", key: "slack_token", label: "Slack bot token", kind: "secret" }, diff --git a/nextjs-frontend/components/settings/settings-shell.tsx b/nextjs-frontend/components/settings/settings-shell.tsx index 214822c56..91a8a403e 100644 --- a/nextjs-frontend/components/settings/settings-shell.tsx +++ b/nextjs-frontend/components/settings/settings-shell.tsx @@ -35,6 +35,7 @@ import { Mail, MessagesSquare, Send, + Hash, PackageCheck, RadioTower, Network, @@ -84,6 +85,7 @@ const ICON: Record = { mail: Mail, bridge: MessagesSquare, telegram: Send, + slack: Hash, telemetry: Activity, fedora: Archive, sensors: RadioTower, diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 6c7b3b86f..ef5db0e0f 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -2624,6 +2624,50 @@ } } }, + "/api/v1/settings/slack": { + "get": { + "tags": [ + "admin" + ], + "summary": "Slack Status", + "description": "How the assistant's Slack app is doing, its slash command, and the link that creates the app from its manifest.", + "operationId": "slack_status", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SlackStatus" + } + } + } + } + } + } + }, + "/api/v1/settings/slack/test": { + "post": { + "tags": [ + "admin" + ], + "summary": "Test Slack", + "description": "Check both Slack tokens, and that the account to answer as exists.", + "operationId": "test_slack", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BridgeTestResult" + } + } + } + } + } + } + }, "/api/v1/settings/documents/node/test": { "post": { "tags": [ @@ -53165,6 +53209,111 @@ ], "title": "SimilarTopic" }, + "SlackStatus": { + "properties": { + "state": { + "type": "string", + "enum": [ + "off", + "incomplete", + "starting", + "running", + "error" + ], + "title": "State", + "description": "off; incomplete (`error` says what's missing); starting (no server process has connected yet); running; error (the connection or the last message failed, `error` says why)" + }, + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error" + }, + "holder": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Holder", + "description": "the server process connected to Slack" + }, + "at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "At", + "description": "when it last heard from Slack" + }, + "answered": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Answered", + "description": "messages it answered" + }, + "team": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Team", + "description": "the Slack workspace it's connected to" + }, + "bot": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Bot", + "description": "the app's bot user" + }, + "command": { + "type": "string", + "title": "Command", + "description": "the slash command, such as /lens" + }, + "create_url": { + "type": "string", + "title": "Create Url", + "description": "where the Slack app is created from its manifest, in one click" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "state", + "command", + "create_url" + ], + "title": "SlackStatus" + }, "SmbStatus": { "properties": { "enabled": { diff --git a/threat-model.md b/threat-model.md index c40b097e2..f2111e1fc 100644 --- a/threat-model.md +++ b/threat-model.md @@ -101,7 +101,7 @@ optional listeners (MQTT, syslog, tunnel, local model server) run inside workers | Web app & API gateway (Web) | `nextjs-frontend/proxy.ts`, `lib/api/backend-proxy.ts`, `next.config.mjs`; `core/middleware.py` Host check and CSP | network | In | | Identity & sessions (Identity) | `routes/{auth,passkeys,oauth,external,setup,users}.py`, `domain/{auth,passkeys,oauth,external_login,iiif_auth}.py`, `core/security.py`, `nextjs-frontend/auth.ts` | DB, OIDC providers, SMTP, logs | In | | Authorization & data API (AuthZ) | `api/deps.py` (`Access`, `Writer`, `Admin*`), `domain/access.py`, `domain/ipgroups.py`, share links, `api/media.py`, `api/iiif.py`, `api/pages.py`, `api/mcp_tools.py` | DB, files | In | -| Outbound fetchers & stored secrets (Outbound) | `domain/netguard.py`, `webcapture.py`, `feeds.py`, `notify.py`, `sources.py`, `llm.py`, `semantic.py`, `speech.py`, `fedora.py`, `bridge.py`, `telegram.py`, `telemetry.py`, `settings.py` seal, `keyring.py`, `vaults.py` | network, child processes, files | In | +| Outbound fetchers & stored secrets (Outbound) | `domain/netguard.py`, `webcapture.py`, `feeds.py`, `notify.py`, `sources.py`, `llm.py`, `semantic.py`, `speech.py`, `fedora.py`, `bridge.py`, `telegram.py`, `slack.py`, `telemetry.py`, `settings.py` seal, `keyring.py`, `vaults.py` | network, child processes, files | In | | Ingest & processing (Ingest) | `routes/{uploads,files,imports}.py`, `domain/{ingest,documents,convert,video,uploads}.py`, `templates.py`, `render.py` | child processes (ffmpeg, LibreOffice, Chromium, poppler, Tesseract), files | In | | Query engines (Query) | `domain/cypher.py`, `domain/rdf.py` (SPARQL), `domain/rdf_import.py`, `domain/search.py` | DB | In | | Assistant & extensions (Assistant) | `domain/{chat,ai_tools,ops_tools,extensions,tool_nodes,flow,custom_nodes,code_tools}.py`, MCP write tools | network (model servers), child process (code tools) | In | @@ -278,7 +278,7 @@ classified by gate only *(inferred, Q8)*; unread modules are listed in Q34. | `/uploads`, `/import`, `/recordings/{rid}/files` | file bytes, name, extension, size | yes, editors | data, type/class, size | none | *(documented, docs/configuration.md "Uploads accept only the types")* | | watched folders, storage sources, IMAP, iCal | remote file names, bytes, mail, events | yes, whoever writes to the remote, mails the box or serves the feed | data, resource-name, size | admin creates sources | *(inferred, Q17)* | | `POST /imports/web`, extension `http` tools, notification targets | URL | yes: editors (web, tools), owners (targets) | resource-name, x-network-destination | none | *(maintainer, 2026-10)* | -| admin settings: model, embeddings, speech, decisions, Fedora, bridge, Telegram bot, telemetry, IIIF import, rclone remotes, IMAP, iCal, MQTT bridge, OIDC issuer | URL, credentials, `api_key_env` | admin only; documented guards still apply (P-ADMIN-GUARD) | resource-name, x-credential | admin is trusted | *(maintainer, 2026-10)* | +| admin settings: model, embeddings, speech, decisions, Fedora, bridge, Telegram bot, Slack app tokens, telemetry, IIIF import, rclone remotes, IMAP, iCal, MQTT bridge, OIDC issuer | URL, credentials, `api_key_env` | admin only; documented guards still apply (P-ADMIN-GUARD) | resource-name, x-credential | admin is trusted | *(maintainer, 2026-10)* | | replies from remote servers | web page HTML and scripts, IIIF manifests, model replies, OIDC discovery, calendars and their redirects | yes, the remote | data, topology | treat as untrusted | *(inferred, Q17)* | | chat, `/graph/ask`, MCP tools | prompt text; model-chosen tool calls | yes; also indirectly through content | data, x-prompt-injection | none | *(documented, docs/assistant.md "limited to what the person can read")* | | Lens extension side panel | answers shown there (model text that can repeat third-party text), the sign-in coming back | yes, indirectly through content | data, x-prompt-injection | none; answers render as Markdown cleaned by DOMPurify (no scripts, images or forms; only http and https links), and the sign-in checks its `state` and PKCE | *(documented, extensions/browser/src/core/assistant.js answerHtml docstring "cleaned of anything that could run or fetch on its own")* | @@ -571,7 +571,7 @@ Exported by phase 3.6 (backtest) and de-identified. Closing rows carry their sta | N-ENUM | Hiding account or object existence outside password sign-in and signed-in 404s | Passkey 404, external messages, anonymous 401 vs 404 | correctness-only | no | *(inferred, Q6)* | | N-AUDIT | Tamper evidence or completeness of the audit and activity logs; sign-in requests are not logged there | operations record only; admins read it | correctness-only | no | *(documented, docs/activity.md "aren't logged here")* | | N-MQTT-SUBSCRIBE | Topic isolation on the MQTT hub: "anything can subscribe to it, with `+` and `#`" | Signed-in or anonymous-when-enabled clients | security-critical | yes: a hub login is not per-stream access | *(documented, docs/sensors.md "anything can subscribe to it")* | -| N-BRIDGE | Per-person access in chat rooms. The bridge (Matterbridge or the Telegram bot) answers as one account, the turning-on admin by default | Everyone in the room reads what that account reads (exposure posture: Q28); the Telegram bot answers only people in `telegram.users` (anyone can find a bot), and nobody until one is let in | security-critical | no | *(documented, docs/chat-rooms.md "answers as the admin who turned it on")* | +| N-BRIDGE | Per-person access in chat rooms. The bridge (Matterbridge, the Telegram bot or the Slack app) answers as one account, the turning-on admin by default | Everyone in the room reads what that account reads (exposure posture: Q28); the Telegram bot answers only people in `telegram.users` (anyone can find a bot), and nobody until one is let in; the Slack app answers everyone in its workspace who can message it unless `slack.users` is set, and sends its bot token only to `files.slack.com` (redirects elsewhere are refused) | security-critical | no | *(documented, docs/chat-rooms.md "answers as the admin who turned it on")* | | N-PUBLIC | Privacy of a public recording's open parts: anyone may use them | Open parts only; closed parts and restricted or private recordings are P-ACCESS-PARTS | correctness-only | no | *(documented, docs/access.md "the parts of a public recording anyone may use")* | | N-DESCRIPTION | Hiding a recording's description when its parts are closed | Anyone who may see the page | correctness-only | no | *(documented, docs/access.md "never a closed part")* | | N-RDF-XML | XML parsing in RDF import. RDF/XML is refused, so XXE and billion-laughs do not apply there | RDF import only, not docx | security-critical | no | *(documented, rdf_import.py docstring "RDF/XML isn't read")* | diff --git a/threat-model.yaml b/threat-model.yaml index b333d9a54..a12136ab7 100644 --- a/threat-model.yaml +++ b/threat-model.yaml @@ -2,7 +2,7 @@ # Authority order: prose > yaml > json. Regenerate whenever the prose changes. schema: threat-model-sidecar/v2 project: lens -prose_version: "threat-model.md@sha256:57e26a9c01bd711bdc650f3647f22a7e7929c4f8ccb15c7b3428d46dd77ffb67" +prose_version: "threat-model.md@sha256:4cb6c6908b83dad40c7a932526b00401acd5b72aba0c8c42832b1d575cec3d26" model_status: under-review triage_policy: strict confidence: {documented: 201, maintainer: 46, inferred: 91, assumption: 8}