From 2e5c74923505e190879fe6e27eb3f59ddb8697ab Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 22:21:04 +0000 Subject: [PATCH 1/2] feat(automations): tell a person in their own chat app, the notify action An automation can now tell someone something. Each chat channel keeps the private chat it last had with someone on its list of people who may talk to Lens (chat_route), and channels.tell sends there, as the account the bot or app answers as. The notify action uses it for "me" (routine: only they read it) and also sends to a namespace's notification target or a Matterbridge gateway, which reach other people and so ask first. Links an injection could fill are broken up when the run read outside text. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01CyjR2zEfmTXBewKAx9Taw5 --- docs/automations.md | 27 +- docs/chat-rooms.md | 6 + fastapi_backend/app/domain/actions.py | 24 +- .../app/domain/actions_messages.py | 204 +++++++++++++++ fastapi_backend/app/domain/bridge.py | 4 + fastapi_backend/app/domain/channels.py | 113 +++++++- fastapi_backend/app/domain/slack.py | 2 + fastapi_backend/app/domain/store.py | 4 + fastapi_backend/app/domain/telegram.py | 1 + .../tests/api/test_actions_messages.py | 244 ++++++++++++++++++ threat-model.json | 2 +- threat-model.md | 2 +- threat-model.yaml | 4 +- 13 files changed, 629 insertions(+), 8 deletions(-) create mode 100644 fastapi_backend/app/domain/actions_messages.py create mode 100644 fastapi_backend/tests/api/test_actions_messages.py diff --git a/docs/automations.md b/docs/automations.md index 0186a4a00..d83c67287 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -16,8 +16,9 @@ merged is called built. | The timeline API (`GET /api/v1/activities`), the MCP tools `timeline` and `event_kinds`, the assistant's `timeline` | built | | The shapes of triggers, joins, an If, policy and intents, checked (`app/domain/automation_spec.py`) | built | | The action registry with risk from each action's effect, and one action, `log_line` (`app/domain/actions.py`) | built | +| Telling a person: the `notify` action and `channels.tell` (their own chat, a notification target, a Matterbridge room) | built | | Settings → Automations: how often followers look and how long the event log is kept | built | -| Storing and running automations, schedules and timers, joins, the real actions, approvals, variables, the timeline page, the studio | planned | +| Storing and running automations, schedules and timers, joins, the other actions, approvals, variables, the timeline page, the studio | planned | ## Contract @@ -247,9 +248,29 @@ policy with the node in `ctx["node"]`): An effect may be worked out from the params (`notify` to "me" is `self`, to a room is `out`); when it can't be worked out, it counts as `out`. An action's own `risk` function may make it stricter, never looser. +An action acts for the automation's person (`run_as`), with their permissions as they are when it runs +(`actions.person`): an automation whose person was switched off or removed does nothing. + | Action | Does | Effect | Output | | --- | --- | --- | --- | | `log_line` | puts a line (`text`, `level` info or warning) in the run's log | read | `{line, level}` | +| `notify` | sends `text` (and a `link`; Lens's own paths become full links) `to` `me` (your own chat app), `target:` (one of the namespace's [notification targets](notifications.md)) or `gateway:` (a Matterbridge room) | self for `me`, else out | `{to, text, sent, failed}`: where it went | + +#### Telling a person + +`notify` to `me` goes through `channels.tell(db, cfg, account, text, links=())`: every chat channel that answers as +your account (the Telegram bot, the Slack app) keeps the private chat it last had with someone on its list of people +who may talk to Lens (`chat_route:`, updated as it answers), and the message goes there. A group or a room is +never used, since it reaches other people, and neither is Matterbridge, where a gateway is a room. With no such chat +the action fails with "no chat app linked", saying how to link one. The result names each channel and chat it used, +so a reply there can be matched to what was sent. + +Chat apps fetch what a message links to show a preview, so a web address built from what the run read would carry it +out before anyone clicks. When the run read text from outside Lens (the intent's `untrusted`), web addresses in the +message are broken up (`hxxps://evil[.]example/...`), except Lens's own; when it read none, the person wrote them and +they stay. The same goes for notification targets and Matterbridge rooms. A notification target must be in one of the +automation's namespaces, switched on, and the automation's person must be able to edit that namespace; a Matterbridge +room needs the bridge on and answering as the automation's person (or the person to be an admin). ## Refine later @@ -260,3 +281,7 @@ worked out, it counts as `out`. An action's own `risk` function may make it stri no row records; pushing instead of polling. - People given only some collections of a namespace see that namespace's activities about those collections. - Name an automation actor by its automation's name once automations are stored. +- Telling a person: buttons on chat approvals (Telegram inline keyboards, Slack Block Kit); email as a `notify` + channel; web push; private chats through Matterbridge (it can't tell them from rooms); with several people let in, + "me" is whoever last wrote privately, until each chat user has a Lens account of their own; telling which links in a + message the person's template wrote, so they stay when the run read outside text. diff --git a/docs/chat-rooms.md b/docs/chat-rooms.md index c73c83c50..6f3044129 100644 --- a/docs/chat-rooms.md +++ b/docs/chat-rooms.md @@ -145,6 +145,12 @@ That's all. Without an account given, it answers as the admin who turned it on. answer looks there and says so once ("Looked in calls"); when it isn't, it looks everywhere and names the likeliest namespaces. **use pods** keeps the conversation in pods until **use everything**. The conversation's scope in Chat shows where the last question looked. +- **Telling you things.** An automation that tells you something ([Automations](automations.md#telling-a-person)) + sends it, as the account the bot or app answers as, to the private chat in Telegram or Slack it last had with + someone on its list of people who may talk to Lens. Nothing goes to a room or a group, which reaches other people + too, and nothing goes through Matterbridge, where Lens can't tell a private chat from a room. Message the bot or app + privately once and messages for you go there; until then an automation's run says "no chat app linked". Web + addresses in them are broken up as answers' are. - **One reader.** Matterbridge hands out each message once, so only one server process reads it: the API and the workers all run the bridge thread, and whichever holds the lease (renewed every look, given up when it stops or the bridge is turned off) does the reading. Settings → Chat rooms says whether it is listening and how many messages it answered. diff --git a/fastapi_backend/app/domain/actions.py b/fastapi_backend/app/domain/actions.py index fc246864b..73a1c77c1 100644 --- a/fastapi_backend/app/domain/actions.py +++ b/fastapi_backend/app/domain/actions.py @@ -9,8 +9,9 @@ - `out` sends outside Lens, reaches other people, or deletes: ask, unless the person set that node to run on its own. When an action node runs, it renders its params and makes an intent (automation_spec.check_intent); `perform` carries -an intent out, or with `dry` says what it would do and changes nothing. One action ships here, `log_line`; the real -ones come with the actions module. +an intent out, or with `dry` says what it would do and changes nothing. An action acts for the automation's person +(`person`), with their permissions as they are when it runs. `log_line` ships here; the other actions are registered by +a module per group, loaded with this one: actions_messages.py (notify). """ from __future__ import annotations @@ -20,6 +21,7 @@ from collections.abc import Callable from dataclasses import dataclass +from . import auth from . import automation_spec as spec_ NAME_RX = re.compile(r"^[a-z][a-z0-9_]{0,40}$") @@ -198,6 +200,21 @@ def perform(db, cfg, intent, user, dry=False): return out +def person(db, intent, user=None): + """The account an intent acts for, as it is now ({id, email, name, admin}): perform's `user`, else the intent's + run_as. ValueError when there's none, or it has been switched off or removed: an automation never acts for nobody.""" + uid = user.get("id") if isinstance(user, dict) else user + if uid is None: + uid = intent.get("run_as") + try: + a = auth.get_account(db, int(uid)) if uid is not None else None + except (TypeError, ValueError): + a = None + if not a or a.get("disabled") or a.get("removed_at"): + raise ValueError("this automation acts for nobody who can sign in: give it a person to run as") + return {"id": a["id"], "email": a["email"], "name": a.get("name") or a["email"], "admin": bool(a.get("admin"))} + + def describe(name, params): """What an action would do, in words.""" spec = get(name) @@ -238,3 +255,6 @@ def _log_line(db, cfg, intent, user, dry): describe=lambda p: f"Write “{p.get('text', '')}” to the run log", ) ) + + +from . import actions_messages # noqa: E402, F401 - registers notify; loaded with the catalog diff --git a/fastapi_backend/app/domain/actions_messages.py b/fastapi_backend/app/domain/actions_messages.py new file mode 100644 index 000000000..66f51e5e3 --- /dev/null +++ b/fastapi_backend/app/domain/actions_messages.py @@ -0,0 +1,204 @@ +"""Automation actions that tell people something (docs/automations.md, Actions): `notify`. + +`notify` sends a message to one of three places, named by its `to`: + +- `me`: the automation's own person, in their chat apps (channels.tell: the private chat each Telegram bot or Slack app + that answers as their account last had with them). Only they read it, so it runs without asking (effect `self`). +- `target:`: one of the namespace's notification targets (notify.py: a signed webhook, Matterbridge, Slack or + Discord), sent the way notifications are. +- `gateway:`: a Matterbridge gateway (a room) through the chat-room bridge (bridge.py). + +The last two reach other people, so they ask first unless the person set that node to run on its own (effect `out`). +Web addresses in the message are broken up (untrusted.defang) unless Lens wrote them or the run read nothing from +outside Lens, since chat apps fetch what they link before anyone clicks: an address built from an email's text would +carry it out. +""" + +from __future__ import annotations + +import re + +from . import actions, activity, auth, bridge, channels, notify, store, untrusted + +TARGET_RX = re.compile(r"^(?:target:)?(\d{1,12})$") +GATEWAY_RX = re.compile(r"^gateway:(\S{1,120})$") +MAX_TEXT = 4000 + + +def _to(p): + return str(p.get("to") or "me").strip() + + +def _effect(p): + return "self" if _to(p) == "me" else "out" + + +def _link(db, cfg, link): + """A link as people open it: Lens's own paths (/resources/7) on the web app's address.""" + link = str(link or "").strip() + if link.startswith("/") and not link.startswith("//"): + from app.email import app_url + + return app_url(cfg, db) + link + return link + + +def _own(cfg, db): + from app.email import app_url + + return [app_url(cfg, db)] + + +def _text(db, cfg, p): + """(the message, its link), as sent.""" + text = str(p.get("text") or "").strip()[:MAX_TEXT] + if not text: + raise ValueError("notify: the message is empty") + return text, _link(db, cfg, p.get("link")) + + +def _keep(intent, text): + """The web addresses that stay as written: all of them when the run read nothing from outside Lens (the person + and Lens wrote the message), else only Lens's own (left to defang).""" + return () if intent.get("untrusted") else untrusted.links(text) + + +def _me(db, cfg, intent, user, dry, text): + acc = actions.person(db, intent, user) + if dry: + found = [channels.where(ch, r) for ch, _, r in channels.routes(db, cfg, acc)] + return {"to": "me", "text": text, "sent": [], "would": found, "error": None if found else channels.NOT_LINKED} + got = channels.tell(db, cfg, acc, text, _keep(intent, text)) + if not got["sent"]: + raise ValueError(f"couldn't tell {acc['name']}: {got['error']}") + return {"to": "me", "text": text, "sent": got["sent"], "failed": got["failed"]} + + +def _target(db, cfg, intent, user, dry, tid, text, link): + try: + t = notify.get(db, tid) + except KeyError: + raise ValueError(f"there's no notification target {tid}") from None + if intent["spaces"] and t["space"] not in intent["spaces"]: + raise ValueError(f"notification target {t['name']} isn't in this automation's namespaces") + acc = actions.person(db, intent, user) + if not auth.allows(auth.roles(db, acc), t["space"], "editor"): + raise ValueError(f"{acc['name']} can't send to {t['name']}: it needs someone who can edit its namespace") + if not t.get("enabled"): + raise ValueError(f"notification target {t['name']} is switched off") + out = {"to": f"target:{tid}", "text": text} + if dry: + return {**out, "sent": [], "would": [{"target": tid, "name": t["name"], "kind": t["kind"]}]} + safe = untrusted.defang(text, _keep(intent, text), _own(cfg, db)) + ns = store.space_names(db).get(t["space"]) + event = notify._event( + "automation.message", + f"automation-{intent['key']}", + t["space"], + ns, + safe, + link or None, + {"automation": intent.get("automation"), "run": intent.get("run"), "node": intent["node"]}, + ) + got = notify.send(db, cfg, t, event, event["id"]) + if not got["ok"]: + raise ValueError(f"notification target {t['name']}: {got['error']}") + return {**out, "sent": [{"target": tid, "name": t["name"], "kind": t["kind"], "code": got["code"]}]} + + +def _gateway(db, cfg, intent, user, dry, gateway, text): + why = bridge.ready(cfg) + if why: + raise ValueError("the chat-room bridge isn't on" if why == "off" else f"the chat-room bridge isn't set up: {why}") + acc = actions.person(db, intent, user) + answers_as = (cfg["bridge"].get("account") or "").strip().lower() + if not acc["admin"] and answers_as != acc["email"].lower(): + raise ValueError("Matterbridge answers as someone else: only they or an admin can post to its gateways") + out = {"to": f"gateway:{gateway}", "text": text} + if dry: + return {**out, "sent": [], "would": [{"gateway": gateway}]} + error = None + try: + bridge.post(cfg, gateway, bridge.safe_links(cfg, db, text, _keep(intent, text))) + except (RuntimeError, OSError, ValueError) as e: + error = str(e) or type(e).__name__ + activity.record("out", "chat.bridge", [], cfg, db, ok=error is None, error="unreachable" if error else None) + if error: + raise ValueError(f"Matterbridge gateway {gateway}: {error}") + return {**out, "sent": [{"channel": "bridge", "label": "Matterbridge", "gateway": gateway}]} + + +def _notify(db, cfg, intent, user, dry): + p = intent["params"] + to = _to(p) + text, link = _text(db, cfg, p) + if to == "me": + return _me(db, cfg, intent, user, dry, text + (f"\n{link}" if link else "")) + m = TARGET_RX.match(to) + if m: + return _target(db, cfg, intent, user, dry, int(m.group(1)), text, link) + m = GATEWAY_RX.match(to) + if m: + return _gateway(db, cfg, intent, user, dry, m.group(1), text + (f"\n{link}" if link else "")) + raise ValueError(f"notify: send to me, target: or gateway:, not {to}") + + +def _short(text, n=80): + text = " ".join(str(text or "").split()) + return text if len(text) <= n else text[: n - 1] + "…" + + +def _describe(p): + to, said = _to(p), _short(p.get("text")) + if to == "me": + return f"Tell me in my chat app: “{said}”" + m = GATEWAY_RX.match(to) + if m: + return f"Post in the Matterbridge gateway {m.group(1)}: “{said}”" + m = TARGET_RX.match(to) + return f"Send to notification target {m.group(1)}: “{said}”" if m else f"Send to {to}: “{said}”" + + +actions.register( + actions.ActionSpec( + name="notify", + label="Send a message", + group="Messages", + description=( + "Tells you in your own chat app (Telegram or Slack, where you last talked to Lens privately), or sends to a " + "notification target or a Matterbridge room, which asks first." + ), + params={ + "type": "object", + "properties": { + "to": { + "type": "string", + "title": "To", + "default": "me", + "maxLength": 200, + "description": "me, target: or gateway:", + }, + "text": {"type": "string", "title": "Message", "maxLength": MAX_TEXT}, + "link": { + "type": "string", + "title": "Link", + "maxLength": 2000, + "description": "Lens's own paths (/resources/7) become full links", + }, + }, + }, + required=("text",), + effect=_effect, + output={ + "type": "object", + "properties": { + "to": {"type": "string"}, + "text": {"type": "string"}, + "sent": {"type": "array", "items": {"type": "object"}}, + "failed": {"type": "array", "items": {"type": "object"}}, + }, + }, + perform=_notify, + describe=_describe, + ) +) diff --git a/fastapi_backend/app/domain/bridge.py b/fastapi_backend/app/domain/bridge.py index aeddcfa93..0c7cdb550 100644 --- a/fastapi_backend/app/domain/bridge.py +++ b/fastapi_backend/app/domain/bridge.py @@ -514,6 +514,10 @@ def handle(db, cfg, base, m, ch=None): return False account = _account(db, cfg) cid = conversation(db, account, m, ns if sid is not None else None, ch.label) + try: # a private chat with someone the channel vouches for is where the account's person is told things + channels.remember(db, cfg, ch, account, m, cid) + except Exception: # noqa: BLE001 - answering comes first + log.warning("%s: couldn't keep where to tell %s things", ch.key, account["email"], exc_info=True) note = None cmd = chat.command(q) if cmd: # /clear or /compact, for this room's conversation diff --git a/fastapi_backend/app/domain/channels.py b/fastapi_backend/app/domain/channels.py index 4520c35f5..f81d07ab3 100644 --- a/fastapi_backend/app/domain/channels.py +++ b/fastapi_backend/app/domain/channels.py @@ -14,6 +14,11 @@ - files: [{ref, filename, size}], files sent with it, held for the assistant to import (import_files) - thread: what identifies the conversation (else gateway, channel, account and username) - namespace: the namespace it's for, when the adapter knows (else the channel's rooms setting says, or Lens picks) +- private: it was said in a private chat with Lens, not in a room (route) + +Telling a person something nobody asked about yet (an automation's message, tell()): each channel keeps the private chat +it last had with someone it vouches for (chat_route:), and tell() sends there, through every channel that +answers as that person's account. A room is never used: it reaches other people too. """ from __future__ import annotations @@ -24,7 +29,7 @@ import secrets import threading -from . import store, uploads, voice +from . import activity, auth, store, uploads, voice from .store import R log = logging.getLogger(__name__) @@ -83,6 +88,24 @@ def handle(self, db, cfg, base, m): return bridge.handle(db, cfg, base, m, self) + def route(self, m): + """Where to tell the account's own person something later, from a message `m` they sent: what send() needs to + reach its private chat again, or None for a message said in a room (which reaches other people too).""" + if not m.get("private"): + return None + out = {k: m[k] for k in ("gateway", "channel", "account", "username", "userid", "thread") if m.get(k) is not None} + to = m.get("to") or {} + if to.get("channel"): # a new message in the chat, never in a thread or through a slash command's address + out["to"] = {"channel": to["channel"]} + return out + + def vouched(self, cfg, m): + """Whether the channel vouches for who sent `m`: they're on its list of people who may talk to Lens (`users`, + by name or id). `cfg` is the channel's view (view()).""" + users = {u.strip().lstrip("@").lower() for u in cfg["bridge"].get("users") or [] if u.strip()} + who = (m.get("username") or "").strip("<> ").lstrip("@").lower() + return bool(users) and (who in users or str(m.get("userid") or "").lower() in users) + def view(cfg, ch): """The settings as bridge.py reads them: the channel's own section as `bridge`.""" @@ -246,3 +269,91 @@ def every(): def start_all(db, cfg_fn, stop, base_fn=None, name=None, log_fn=None): """A thread per channel (each idle while it's off).""" return [start(db, cfg_fn, stop, ch, base_fn, name, log_fn) for ch in every()] + + +# ---------- telling a person ---------- +NOT_LINKED = ( + "no chat app linked: message Lens in a private chat in Telegram or Slack, as someone on its list of people who may " + "talk to Lens, and messages for you go there" +) + + +def remember(db, cfg, ch, account, m, conversation=None): + """Keep the private chat `m` was said in as where the account's own person is told things (chat_route:), + when the channel vouches for its sender; the latest one wins. `cfg` is the channel's view. True when kept.""" + target = ch.route(m) + if not target or not ch.vouched(cfg, m): + return False + who = (m.get("username") or "").strip("<> ") or str(m.get("userid") or "someone") + row = { + "channel": ch.key, + "account": account["id"], + "email": account["email"], + "target": target, + "chat": f"private chat with {who}", + "conversation": conversation, + "at": store.now(), + } + db.q("UPSERT $r CONTENT $d", r=R("chat_route", ch.key), d=store.clean(row)) + return True + + +def _account(db, account): + if isinstance(account, dict) and account.get("email"): + return account + got = auth.get_account(db, account["id"] if isinstance(account, dict) else account) + return got if got and not got.get("disabled") else None + + +def routes(db, cfg, account): + """Where `account`'s own person can be told something now: [(channel, its view, its chat_route)] for each channel + that is on, answers as that account, and last had a private chat with someone it still vouches for.""" + acc = _account(db, account) + if not acc: + return [] + rows = {r["channel"]: r for r in db.rows("SELECT * OMIT id FROM chat_route WHERE account = $a", a=acc["id"])} + out = [] + for ch in every(): + r = rows.get(ch.key) + if not r or ch.ready(cfg): + continue + v = view(cfg, ch) + if (v["bridge"].get("account") or "").strip().lower() != (acc.get("email") or "").strip().lower(): + continue # it answers as someone else now + if ch.vouched(v, r["target"]): + out.append((ch, v, r)) + return out + + +def where(ch, r): + """Where a message went, as tell() reports it.""" + return store.clean( + {"channel": ch.key, "label": ch.label, "chat": r.get("chat"), "conversation": r.get("conversation"), "target": r["target"]} + ) + + +def tell(db, cfg, account, text, links=()): + """Tell `account`'s own person `text` in their chat apps: through each channel that answers as that account, in the + private chat it last had with someone it vouches for (routes()). Web addresses in it are broken up as a room's + answers' are (bridge.safe_links) unless they are in `links` (what the person or Lens wrote) or Lens's own. + Returns {sent: [{channel, label, chat, conversation, target}], failed: [{channel, error}], error}, `error` saying + why nothing was sent (NOT_LINKED when no channel can reach them).""" + from . import bridge + + found = routes(db, cfg, account) + sent, failed = [], [] + for ch, v, r in found: + error = None + try: + ch.send(v, r["target"], bridge.safe_links(v, db, text, links)) + except (ChannelError, RuntimeError, OSError, ValueError) as e: + error = str(e) or type(e).__name__ + failed.append({"channel": ch.key, "error": error}) + log.warning("%s: couldn't tell %s: %s", ch.key, r.get("email"), error) + else: + sent.append(where(ch, r)) + activity.record( + "out", f"chat.{ch.key}", [f"account:{r['account']}"], cfg, db, ok=error is None, error="unreachable" if error else None + ) + error = None if sent else ("; ".join(f"{f['channel']}: {f['error']}" for f in failed) if failed else NOT_LINKED) + return {"sent": sent, "failed": failed, "error": error} diff --git a/fastapi_backend/app/domain/slack.py b/fastapi_backend/app/domain/slack.py index 74c3f1a9d..32bd99766 100644 --- a/fastapi_backend/app/domain/slack.py +++ b/fastapi_backend/app/domain/slack.py @@ -231,6 +231,7 @@ def message(me, team, event, names): "text": text, "event": "", "direct": private or mentioned, + "private": private, "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")} @@ -259,6 +260,7 @@ def slash(me, team, p, names): "text": text or "Hello! What can you do?", "event": "", "direct": True, + "private": private, "voice": None, "files": [], "thread": ["slack", team, cid, uid], diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 66826a91b..209326054 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -1308,6 +1308,10 @@ def close(self): # the chat-room bridge (bridge.py): which process reads Matterbridge (bridge_state:lease); its conversations are # chats with a `bridge` key (the room and person) "DEFINE TABLE IF NOT EXISTS bridge_state SCHEMALESS", + # where each chat channel tells its account's person things nobody asked about yet (chat_route:: the + # private chat it last had with someone it vouches for; channels.tell) + "DEFINE TABLE IF NOT EXISTS chat_route SCHEMALESS", + "DEFINE INDEX IF NOT EXISTS chat_route_account ON chat_route FIELDS account", # templates, pipelines, outputs, chat, edits "DEFINE TABLE IF NOT EXISTS template SCHEMALESS", "DEFINE TABLE IF NOT EXISTS template_version SCHEMALESS", diff --git a/fastapi_backend/app/domain/telegram.py b/fastapi_backend/app/domain/telegram.py index 77808f73e..282e4a645 100644 --- a/fastapi_backend/app/domain/telegram.py +++ b/fastapi_backend/app/domain/telegram.py @@ -125,6 +125,7 @@ def message(me, msg): "text": text, "event": "", "direct": private or mentioned or replied, + "private": private, "voice": vn.get("file_id"), "files": _files(msg), "thread": ["telegram", chat["id"], who.get("id")], diff --git a/fastapi_backend/tests/api/test_actions_messages.py b/fastapi_backend/tests/api/test_actions_messages.py new file mode 100644 index 000000000..afe8c3136 --- /dev/null +++ b/fastapi_backend/tests/api/test_actions_messages.py @@ -0,0 +1,244 @@ +"""Automations telling people things (docs/automations.md, Actions): each chat channel keeps the private chat it last +had with someone it vouches for, channels.tell sends there as the account's person, and the `notify` action reaches +them, a notification target or a Matterbridge room, with links an injection could fill broken up.""" + +from __future__ import annotations + +import pytest + +from app.domain import actions, channels, notify, slack, store, telegram +from tests import fake_llm, fake_matterbridge, fake_slack, fake_telegram +from tests.api._assist import start_llm +from tests.api.test_notifications import Inbox +from tests.helpers import make_user, seed + +update = fake_telegram.update +EVIL = "https://evil.example/x?d=secret" + + +@pytest.fixture +def tg(): + srv, url = fake_telegram.start() + telegram._BOTS.clear() + yield fake_telegram.Handler, url + 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 people(app, db, cfg, folder): + seed(db, cfg, folder) + cfg["ai"]["tools"] = False + return { + "me": make_user(db, "me@x.io", "my password 1", roles={"pods": "editor"}), + "other": make_user(db, "other@x.io", "other password 1", roles={"pods": "viewer"}), + "root": make_user(db, "root@x.io", "root password 1", admin=True), + "pods": store.ns_id(db, "pods"), + } + + +@pytest.fixture +def bot(people, cfg, tg): + """The Telegram bot answering as me@x.io, letting alice, bob and user 10 in.""" + h, url = tg + cfg["telegram"] = { + **cfg["telegram"], + "enabled": True, + "api_url": url, + "token": fake_telegram.TOKEN, + "account": "me@x.io", + "users": ["alice", "bob", "10"], + } + return h + + +def tick(db, cfg): + return channels.tick(db, cfg, cfg, "api-1", telegram.TELEGRAM) + + +def intent(people, **kw): + params = kw.pop("params", {}) + return { + "key": "51-n7", + "action": "notify", + "params": params, + "effect": "self", + "risk": "routine", + "untrusted": True, + "spaces": [people["pods"]], + "run_as": people["me"], + "node": "n7", + "automation": 4, + "run": 51, + **kw, + } + + +def test_the_private_chat_last_had_with_someone_let_in_is_where_a_person_is_told_things(db, cfg, bot, people): + bot.updates = [ + update("Lens, hi", chat_id=-100, chat_type="group", title="Team"), # a room reaches other people + update("hi", user="eve", user_id=66, chat_id=66), # not let in + ] + tick(db, cfg) + assert not db.rows("SELECT * FROM chat_route") + assert channels.tell(db, cfg, people["me"], "hello") == {"sent": [], "failed": [], "error": channels.NOT_LINKED} + bot.updates = [update("what's new?")] # alice, privately + assert tick(db, cfg) == 1 + route = db.one("SELECT * OMIT id FROM chat_route:telegram") + assert route["account"] == people["me"] and route["chat"] == "private chat with alice" and route["conversation"] + bot.sent = [] + got = channels.tell(db, cfg, people["me"], f"Trip on Friday {EVIL}") + assert [(s["channel"], s["chat"]) for s in got["sent"]] == [("telegram", "private chat with alice")] and not got["error"] + assert bot.sent == [{"chat_id": "42", "text": "Trip on Friday hxxps://evil[.]example/x?d=secret"}] # defanged + channels.tell(db, cfg, people["me"], f"Trip {EVIL}", links={EVIL}) # what the person or Lens wrote stays + assert bot.sent[-1]["text"] == f"Trip {EVIL}" + # the latest private chat wins; a group message doesn't move it + bot.updates = [update("hello", user="bob", user_id=8, chat_id=43), update("Lens, hi", user="bob", user_id=8, chat_id=-100, chat_type="group")] + tick(db, cfg) + channels.tell(db, cfg, people["me"], "hello bob") + assert bot.sent[-1]["chat_id"] == "43" + # only as the account the bot answers as, and only to someone it still lets in + assert channels.tell(db, cfg, people["other"], "x")["error"] == channels.NOT_LINKED + cfg["telegram"]["users"] = ["alice"] + assert not channels.routes(db, cfg, people["me"]) + cfg["telegram"]["users"] = ["alice", "bob"] + cfg["telegram"]["account"] = "other@x.io" + assert not channels.routes(db, cfg, people["me"]) + cfg["telegram"]["account"] = "me@x.io" + cfg["telegram"]["enabled"] = False + assert not channels.routes(db, cfg, people["me"]) + + +def test_notify_tells_me_in_my_chat_app(db, cfg, bot, people): + bot.updates = [update("hi")] + tick(db, cfg) + bot.sent = [] + notify_ = actions.get("notify") + ctx = {"automation": {"id": 4, "spaces": [people["pods"]]}, "node": "n7"} + assert actions.resolve_risk(notify_, {"to": "me", "text": "x"}, ctx) == "routine" # only they read it + assert actions.resolve_risk(notify_, {"text": "x"}, ctx) == "routine" # to me unless said otherwise + for to in ("target:3", "gateway:family", "{{ vars.room }}"): # anywhere else, or a reach a template decides, asks + assert actions.resolve_risk(notify_, {"to": to, "text": "x"}, ctx) == "ask" + assert actions.resolve_risk(notify_, {"to": "gateway:family", "text": "x"}, ctx, {"n7": "auto"}) == "routine" + assert actions.describe("notify", {"to": "me", "text": "Trip on Friday"}) == "Tell me in my chat app: “Trip on Friday”" + i = intent(people, params={"text": f"Trip on Friday, see {EVIL}", "link": "/resources/7"}) + dry = actions.perform(db, cfg, i, {"id": people["me"]}, dry=True) + assert dry["sent"] == [] and dry["would"][0]["chat"] == "private chat with alice" and not bot.sent + got = actions.perform(db, cfg, i, {"id": people["me"]}) + assert got["to"] == "me" and got["sent"][0]["channel"] == "telegram" + from app.email import app_url + + text = bot.sent[-1]["text"] + assert "hxxps://evil[.]example" in text and text.endswith(f"\n{app_url(cfg, db)}/resources/7") # Lens's own link stays + # a run that read nothing from outside Lens: the person wrote every link + actions.perform(db, cfg, intent(people, untrusted=False, params={"text": f"see {EVIL}"}), {"id": people["me"]}) + assert bot.sent[-1]["text"] == f"see {EVIL}" + with pytest.raises(ValueError, match="couldn't tell other: no chat app linked"): + actions.perform(db, cfg, intent(people, run_as=people["other"], params={"text": "x"}), None) + db.q("UPDATE $r SET disabled = true", r=store.R("account", people["other"])) + with pytest.raises(ValueError, match="acts for nobody"): + actions.perform(db, cfg, intent(people, run_as=people["other"], params={"text": "x"}), None) + with pytest.raises(ValueError, match="send to me, target: or gateway:"): + actions.perform(db, cfg, intent(people, params={"to": "everyone", "text": "x"}), None) + + +def test_notify_sends_to_a_notification_target(db, cfg, people): + inbox = Inbox() + try: + cfg["notifications"] = {**(cfg.get("notifications") or {}), "networks": ["127.0.0.0/8"]} + t, _ = notify.create(db, cfg, people["pods"], "Family hook", "webhook", inbox.url + "/hook") + i = intent(people, effect="out", risk="ask", params={"to": f"target:{t['id']}", "text": f"Trip {EVIL}", "link": "/resources/7"}) + assert actions.perform(db, cfg, i, None, dry=True)["would"] == [{"target": t["id"], "name": "Family hook", "kind": "webhook"}] + assert not inbox.got + got = actions.perform(db, cfg, i, None) + assert got["sent"] == [{"target": t["id"], "name": "Family hook", "kind": "webhook", "code": 200}] + body = inbox.json() + assert body["type"] == "automation.message" and body["text"] == "Trip hxxps://evil[.]example/x?d=secret" + assert body["url"].endswith("/resources/7") and body["data"] == {"automation": 4, "run": 51, "node": "n7"} + assert inbox.got[-1]["headers"]["webhook-signature"].startswith("v1,") + assert actions.perform(db, cfg, {**i, "params": {**i["params"], "to": str(t["id"])}}, None)["sent"] # a bare id too + with pytest.raises(ValueError, match="isn't in this automation's namespaces"): + actions.perform(db, cfg, {**i, "spaces": [store.ns_id(db, "calls")]}, None) + with pytest.raises(ValueError, match="other can't send to Family hook"): + actions.perform(db, cfg, {**i, "run_as": people["other"]}, None) # a viewer of pods + notify.update(db, cfg, t["id"], people["pods"], {"enabled": False}) + with pytest.raises(ValueError, match="Family hook is switched off"): + actions.perform(db, cfg, i, None) + with pytest.raises(ValueError, match="there's no notification target 999"): + actions.perform(db, cfg, {**i, "params": {"to": "target:999", "text": "x"}}, None) + inbox.status = 500 + notify.update(db, cfg, t["id"], people["pods"], {"enabled": True}) + with pytest.raises(ValueError, match="Family hook: HTTP 500"): + actions.perform(db, cfg, i, None) + finally: + inbox.srv.shutdown() + + +def test_notify_posts_in_a_matterbridge_gateway(db, cfg, people): + srv, url = fake_matterbridge.start() + try: + h = fake_matterbridge.Handler + h.posted = [] + i = intent(people, effect="out", risk="ask", params={"to": "gateway:family", "text": f"Trip {EVIL}"}) + with pytest.raises(ValueError, match="the chat-room bridge isn't on"): + actions.perform(db, cfg, i, None) + cfg["bridge"] = {**cfg["bridge"], "enabled": True, "url": url, "token": "mb-token", "account": "root@x.io"} + with pytest.raises(ValueError, match="Matterbridge answers as someone else"): + actions.perform(db, cfg, i, None) + cfg["bridge"]["account"] = "me@x.io" + assert actions.perform(db, cfg, i, None, dry=True)["would"] == [{"gateway": "family"}] and not h.posted + got = actions.perform(db, cfg, i, None) + assert got["sent"] == [{"channel": "bridge", "label": "Matterbridge", "gateway": "family"}] + assert h.posted[-1]["gateway"] == "family" and h.posted[-1]["text"] == "Trip hxxps://evil[.]example/x?d=secret" + cfg["bridge"]["account"] = "other@x.io" # an admin's automation may post as the bridge's account + assert actions.perform(db, cfg, {**i, "run_as": people["root"]}, None)["sent"] + finally: + srv.shutdown() + + +def test_a_slack_direct_message_is_a_private_chat(monkeypatch, db, cfg, people): + srv, url = fake_slack.start() + sock = fake_slack.Socket() + monkeypatch.setattr(slack, "API", url + "/api") + monkeypatch.setattr(slack, "_connect", lambda u: sock) + fake_slack.Handler.url, fake_slack.Handler.socket = url, sock + try: + cfg["slack"] = { + **cfg["slack"], + "enabled": True, + "bot_token": fake_slack.BOT, + "app_token": fake_slack.APP, + "account": "me@x.io", + "users": ["alice"], + } + for e in (fake_slack.event("Lens, hi"), fake_slack.event("hi", channel="D1", channel_type="im", thread_ts="3.0")): + sock.envelopes.put(e) + lst = None + for _ in range(50): + channels.tick(db, cfg, cfg, "api-1", slack.SLACK) + lst = slack._LISTENERS.get("socket") + if lst and lst.taken >= 2 and lst.todo.empty(): + break + route = db.one("SELECT * OMIT id FROM chat_route:slack") + assert route["target"]["to"] == {"channel": "D1"} and route["chat"] == "private chat with alice" + fake_slack.Handler.posted = [] + assert channels.tell(db, cfg, people["me"], "hello")["sent"][0]["channel"] == "slack" + assert fake_slack.Handler.posted[-1]["channel"] == "D1" and "thread_ts" not in fake_slack.Handler.posted[-1] + finally: + for lst in slack._LISTENERS.values(): + lst.stop.set() + slack._LISTENERS.clear() + srv.shutdown() diff --git a/threat-model.json b/threat-model.json index 47583d519..6050cb92d 100644 --- a/threat-model.json +++ b/threat-model.json @@ -1481,7 +1481,7 @@ }, { "property": "N-BRIDGE", - "reason": "per-person access in chat rooms; the bridge answers as one account, the turning-on admin by default; everyone in the room reads what that account reads (exposure posture: Q28)", + "reason": "per-person access in chat rooms; the bridge answers as one account, the turning-on admin by default; everyone in the room reads what that account reads (exposure posture: Q28); an automation's message to its own person goes to the private chat a channel last had with someone on its users list, never to a room", "false_friend": false, "provenance": "documented", "source": "docs/chat-rooms.md \"answers as the admin who turned it on\"" diff --git a/threat-model.md b/threat-model.md index 7cebe6800..8ea37dfed 100644 --- a/threat-model.md +++ b/threat-model.md @@ -591,7 +591,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, the Telegram bot, the Slack app or the assistant's mailbox) 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); the mailbox answers only addresses in `mailbox.users` whose provider vouched for From (`Authentication-Results`), replies only to From, and never tells a stranger it read their mail | 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, the Slack app or the assistant's mailbox) 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); the mailbox answers only addresses in `mailbox.users` whose provider vouched for From (`Authentication-Results`), replies only to From, and never tells a stranger it read their mail; an automation telling the account's person something (`notify` to me, `channels.tell`) goes to the private chat the Telegram bot or Slack app last had with someone on its `users` list, so with several people let in it may reach another of them, who already reads what the account reads; never to a room | security-critical | no | *(documented, docs/chat-rooms.md "answers as the admin who turned it on")* | | N-PUBLIC | Privacy of a public asset's open parts: anyone may use them | Open parts only; closed parts and restricted or private assets are P-ACCESS-PARTS | correctness-only | no | *(documented, docs/access.md "the parts of a public asset anyone may use")* | | N-DESCRIPTION | Hiding an asset'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-NSFW | Access control from NSFW classification. Blurring and hiding flagged resources are display preferences of the web app, and the score can be wrong | Anyone who may read a resource still opens it, sees its pictures (`sensitive=include`, signed frame links, public pages, IIIF, embeds) and reads its classification | correctness-only | yes: "hidden" reads as restricted | *(documented, docs/nsfw.md "display preferences, not access control")* | diff --git a/threat-model.yaml b/threat-model.yaml index 44972f1d9..697345708 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:57d608a9097062f83292cc010b6762eb2d823ccd4e6743ab243ba80c870f4759" +prose_version: "threat-model.md@sha256:f945beb5f2a168c5de0f0753b98ea3cf4bf37e56d23c021589775c65f6898e0d" model_status: under-review triage_policy: strict confidence: {documented: 201, maintainer: 46, inferred: 91, assumption: 8} @@ -1698,7 +1698,7 @@ properties_disclaimed: - {id: N-ENUM, components: [identity], tier: correctness-only, false_friend: false, conditions: "hiding account or object existence outside password sign-in and signed-in 404s: passkey 404, external messages, anonymous 401 vs 404", provenance: {kind: inferred, question_id: Q6}} - {id: N-AUDIT, components: [identity, authz], tier: correctness-only, false_friend: false, conditions: "tamper evidence or completeness of the audit and activity logs; sign-in requests are not logged there; operations record only; admins read it", provenance: {kind: documented, source: 'docs/activity.md "aren''t logged here"'}} - {id: N-MQTT-SUBSCRIBE, components: [optional], tier: security-critical, false_friend: true, conditions: "topic isolation on the MQTT hub: anything can subscribe to it, with + and #; signed-in or anonymous-when-enabled clients", x-false-friend-note: "a hub login is not per-stream access", provenance: {kind: documented, source: 'docs/sensors.md "anything can subscribe to it"'}} - - {id: N-BRIDGE, components: [outbound], tier: security-critical, false_friend: false, conditions: "per-person access in chat rooms; the bridge (Matterbridge, the Telegram bot or the assistant's mailbox) answers as one account, the turning-on admin by default; everyone in the room reads what that account reads (exposure posture: Q28); the mailbox answers only mailbox.users whose provider vouched for From", provenance: {kind: documented, source: 'docs/chat-rooms.md "answers as the admin who turned it on"'}} + - {id: N-BRIDGE, components: [outbound], tier: security-critical, false_friend: false, conditions: "per-person access in chat rooms; the bridge (Matterbridge, the Telegram bot or the assistant's mailbox) answers as one account, the turning-on admin by default; everyone in the room reads what that account reads (exposure posture: Q28); the mailbox answers only mailbox.users whose provider vouched for From; an automation's message to its own person goes to the private chat a channel last had with someone on its users list, never to a room", provenance: {kind: documented, source: 'docs/chat-rooms.md "answers as the admin who turned it on"'}} - {id: N-PUBLIC, components: [authz], tier: correctness-only, false_friend: false, conditions: "privacy of a public asset's open parts: anyone may use them; open parts only; closed parts and restricted or private assets are P-ACCESS-PARTS", provenance: {kind: documented, source: 'docs/access.md "the parts of a public asset anyone may use"'}} - {id: N-DESCRIPTION, components: [authz], tier: correctness-only, false_friend: false, conditions: "hiding an asset's description when its parts are closed; anyone who may see the page", provenance: {kind: documented, source: 'docs/access.md "never a closed part"'}} - {id: N-NSFW, components: [web, authz], tier: correctness-only, false_friend: true, conditions: "access control from NSFW classification; blurring and hiding flagged resources are display preferences of the web app, and the score can be wrong; anyone who may read a resource still opens it, sees its pictures (sensitive=include, signed frame links, public pages, IIIF, embeds) and reads its classification", x-false-friend-note: "'hidden' reads as restricted", provenance: {kind: documented, source: 'docs/nsfw.md "display preferences, not access control"'}} From 77444d41161a5dcbe506cc79b579e329e23fac5a Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 22:27:10 +0000 Subject: [PATCH 2/2] style: format the notify tests Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01CyjR2zEfmTXBewKAx9Taw5 --- fastapi_backend/tests/api/test_actions_messages.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/fastapi_backend/tests/api/test_actions_messages.py b/fastapi_backend/tests/api/test_actions_messages.py index afe8c3136..08934b922 100644 --- a/fastapi_backend/tests/api/test_actions_messages.py +++ b/fastapi_backend/tests/api/test_actions_messages.py @@ -106,7 +106,10 @@ def test_the_private_chat_last_had_with_someone_let_in_is_where_a_person_is_told channels.tell(db, cfg, people["me"], f"Trip {EVIL}", links={EVIL}) # what the person or Lens wrote stays assert bot.sent[-1]["text"] == f"Trip {EVIL}" # the latest private chat wins; a group message doesn't move it - bot.updates = [update("hello", user="bob", user_id=8, chat_id=43), update("Lens, hi", user="bob", user_id=8, chat_id=-100, chat_type="group")] + bot.updates = [ + update("hello", user="bob", user_id=8, chat_id=43), + update("Lens, hi", user="bob", user_id=8, chat_id=-100, chat_type="group"), + ] tick(db, cfg) channels.tell(db, cfg, people["me"], "hello bob") assert bot.sent[-1]["chat_id"] == "43"