From 7da63504dc8ad39d78faa65dcd57fd23f668285c Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 16 Oct 2026 00:06:03 +0000 Subject: [PATCH] feat(automations): decide an automation's approval with a yes in your chat app A yes in the private chat Lens told you in approves an automation's action that changes something inside Lens, under the room rules: approving on, the sender on the channel's list, and it the one thing waiting there (or named by its number). One that reaches outside Lens is decided on its card; no declines either. The message says to reply yes only where a yes would count. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01VF3LK1DBx3dXX2b8c5T3cQ --- docs/automations.md | 31 ++- docs/chat-rooms.md | 5 +- fastapi_backend/app/domain/approvals.py | 35 +++- fastapi_backend/app/domain/bridge.py | 51 ++++- fastapi_backend/app/domain/channels.py | 8 +- .../tests/api/test_approvals_chat.py | 179 ++++++++++++++++++ threat-model.json | 2 +- threat-model.md | 2 +- threat-model.yaml | 4 +- 9 files changed, 284 insertions(+), 33 deletions(-) create mode 100644 fastapi_backend/tests/api/test_approvals_chat.py diff --git a/docs/automations.md b/docs/automations.md index 178bf6388..6b566f784 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -36,7 +36,8 @@ merged is called built. | Actions that wait (`delay`, `when`): kept as timers, carried out at their time, asking first when they should then ([Time](#time)) | built | | The Timeline page with filters, grouping, review keys and new items, and Home's Latest card ([Timeline](timeline.md)) | built | | Approvals: an automation's action that asks first waits for your pick (approve, decline, edit, allow from now on), told once in your chat app, capped and expiring (`app/domain/approvals.py`) | built | -| The Approvals page and its badge, a yes in your chat app, approval activities and notifications, agents' approval tools | planned | +| Deciding an automation's action with a yes in the chat it told you in | built | +| The Approvals page and its badge, approval activities and notifications, agents' approval tools | planned | | Storing and running automations, joins, variables, the studio | planned | ## Contract @@ -601,10 +602,23 @@ Deciding (`POST /api/v1/approvals/{aid}`): - `always` approves it, then lets that action node run without asking from now on (the automation's policy, `auto`). Only an action that reaches outside Lens or other people asks each time, so only those can be allowed. -Approving, editing and `always` are yours: signed in to Lens, on the approval's card. An API key, an app, MCP and the -assistant can list and decline approvals, never approve them, since approving is the person's pick; each approval's -`can` says what the caller may do with it. This is the one place where an agent can't do what you can. The -assistant's own approvals in a conversation are decided as before. +Approving, editing and `always` are yours: signed in to Lens, on the approval's card, or approving with a yes in your +own chat app (below). An API key, an app, MCP and the assistant can list and decline approvals, never approve them, +since approving is the person's pick; each approval's `can` says what the caller may do with it. This is the one +place where an agent can't do what you can. The assistant's own approvals in a conversation are decided as before. + +**In your chat app.** A reply of "yes" in the private chat you were told in approves an automation's action, under +the rules a chat room's approvals follow ([Chat rooms](chat-rooms.md#what-it-does)), and only when all of these hold: + +- the action changes something inside Lens (effect `lens`); one that reaches outside Lens or other people is + approved on its card in Lens, and the reply says where; +- the channel lets you approve there (approving in the room is on, and you are on its list of people who may talk to + Lens); +- it is the only thing waiting in that chat: with several, a bare "yes" lists them and "yes 12" picks one ("yes all" + leaves an automation's actions waiting, to be picked one at a time). + +"No" declines it, whatever it does. The message that told you says "Reply “yes” to do it or “no” not to" only when a +yes there would count; otherwise it gives the link. Undecided approvals expire after `automations.approval_days` (Settings → Automations, 1–365, default 7): a sweep called from the scheduler once an hour marks them `expired`, nothing runs, and the run says so. The assistant's own @@ -768,6 +782,7 @@ the timer was cancelled, or Lens was off past the catch-up window. source pages, so narrow it by account if that proves slow. - Lens itself: a run held over budget, waiting for someone's pick, as an activity of its own; backups taken before upgrades or with `lens backup` (only those from Settings, the API and the schedule are activities today). -- Approvals: a cost estimate on actions that ask (a run on another asset could say what it would cost); buttons in - Telegram and Slack; approvals that need two people; one card for many alike ("approve all 12"); trying a failed one - again; expiring an automation's approvals when it is removed. +- Approvals: a cost estimate on actions that ask (a run on another asset could say what it would cost); approve + buttons in Telegram and Slack (today a yes decides only actions inside Lens); approvals that need two people; one + card for many alike ("approve all 12"); trying a failed one again; expiring an automation's approvals when it is + removed. diff --git a/docs/chat-rooms.md b/docs/chat-rooms.md index 9770076d4..d8c69fa3c 100644 --- a/docs/chat-rooms.md +++ b/docs/chat-rooms.md @@ -119,7 +119,10 @@ That's all. Without an account given, it answers as the admin who turned it on. several waiting, "yes all" or "yes 12". Only the chat usernames listed may message Lens and approve, so it needs that list; **Approving in the room: only in the web app** turns it off. Settings, imports, batch runs, extensions and forgetting are always approved in the web app. Each approval is in the audit log with "via chat room" and who - said yes. Without a list, anyone in the room may be someone the account doesn't vouch for, so their messages count + said yes. An [automation's action](automations.md#approvals) that changes something inside Lens is approved the same + way, in the private chat it told you about it in, when it's the only thing waiting there (or by its number); one + that reaches outside Lens or other people is approved on its card in Lens, and "no" declines either. + Without a list, anyone in the room may be someone the account doesn't vouch for, so their messages count as text from outside Lens: web tools and other servers' tools wait for approval in the web app too ([third-party content](assistant.md#third-party-content-and-prompt-injection)). - **Links it can't be made to send.** Slack, Telegram, WhatsApp and most chat apps open the links in a message to diff --git a/fastapi_backend/app/domain/approvals.py b/fastapi_backend/app/domain/approvals.py index e0b70edf7..2813b0214 100644 --- a/fastapi_backend/app/domain/approvals.py +++ b/fastapi_backend/app/domain/approvals.py @@ -122,12 +122,26 @@ def link(cfg, db, aid): return f"{app_url(cfg, db)}/approvals?id={aid}" -def message(name, what, url): - """What the person is told when an automation's action waits for them.""" +def message(name, what, url, yes=False): + """What the person is told when an automation's action waits for them; `yes`: a reply there decides it.""" said = what[:1].lower() + what[1:] if what else "do something" + if yes: + return f"{name} wants to {said}. Reply “yes” to do it or “no” not to, or open {url} to decide." return f"{name} wants to {said}. Open {url} to decide." +def yes_counts(db, v, r, aid, effect): + """Whether a yes in the chat of chat_route `r` (channel view `v`) would decide approval `aid`: only for an action + that changes something inside Lens (one that reaches outside is decided on its card), when the channel lets the + person in that chat approve (bridge.room_approver: approving on, and they're on its list of people), and when + nothing else waits in that chat (a bare yes would be ambiguous).""" + from . import bridge + + if effect != "lens" or r.get("conversation") is None or not bridge.room_approver(v, r.get("target") or {}): + return False + return not [a for a in bridge.pending(db, r["conversation"], r.get("account")) if a["id"] != aid] + + def ask(db, cfg, intent, event=None): """An approval for an intent that asks first (the engine's hand-off): the row, for the automation's person, with what it would do, the activity that caused it (`event`, else the run's last) and when it expires; then the person @@ -174,17 +188,22 @@ def ask(db, cfg, intent, event=None): } ), ) - told = tell(db, cfg, person, aid, name, what) + told = tell(db, cfg, person, aid, name, what, i["effect"]) if told: db.q("UPDATE $r SET told = $t", r=R("approval", aid), t=told) return aid -def tell(db, cfg, person, aid, name, what): - """Tell the person once, in their own chat apps, that something waits: the chats it went to.""" +def tell(db, cfg, person, aid, name, what, effect=None): + """Tell the person once, in their own chat apps, that something waits, saying a reply decides it where it would + (yes_counts): the chats it went to.""" url = link(cfg, db, aid) + + def text(ch, v, r): + return message(name, what, url, yes_counts(db, v, r, aid, effect)) + try: - got = channels.tell(db, cfg, person, message(name, what, url), links=(url,)) + got = channels.tell(db, cfg, person, text, links=(url,)) except Exception: # noqa: BLE001 - the approval waits in the inbox either way log.warning("approval %s: couldn't tell %s", aid, person.get("email"), exc_info=True) return [] @@ -319,7 +338,9 @@ def decide(db, cfg, row, user, decision="approve", params=None, via="web"): with ( activity.scope(db, f"automation:{intent['automation']}", f"automation_run:{intent['run']}", cfg=cfg), events.caused_by(cause), - graph_history.acting(actor=who["email"], via=who["id"], why=f"approved by {user.get('email')}", approval=row["id"]), + graph_history.acting( + actor=who["email"], via=who["id"], why=None if via == "chat" else f"approved by {user.get('email')}", approval=row["id"] + ), ): result = actions.perform(db, cfg, {**intent, "status": "waiting"}, person) except Exception as e: # noqa: BLE001 - recorded on the approval and the run diff --git a/fastapi_backend/app/domain/bridge.py b/fastapi_backend/app/domain/bridge.py index 974afd687..491b2f4f7 100644 --- a/fastapi_backend/app/domain/bridge.py +++ b/fastapi_backend/app/domain/bridge.py @@ -18,7 +18,9 @@ The assistant's reversible changes (entity merges and edits, new namespaces: ROOM_SAFE) can be approved by replying "yes" (or "no") in the room, when bridge.approve is "low_risk" and the sender is one of bridge.users; everything else -waits for approval in the web app, linked from the answer. +waits for approval in the web app, linked from the answer. So can an automation's action that changes something inside +Lens, in the private chat its person was told about it in (approvals.ask), when it's the only thing waiting there or +named by its number; one that reaches outside Lens is decided on its card in Lens. What happens in a room is the same in every chat channel (channels.py): Matterbridge is one adapter, Telegram's own bot (telegram.py) another. handle() takes a message from any of them, with their voice notes (transcribed) and files @@ -398,24 +400,36 @@ def room_approver(cfg, m=None): return (m.get("username") or "").strip("<> ").lower() in allowed or (m.get("userid") or "").lower() in allowed -def pending(db, cid): - return db.rows("SELECT record::id(id) AS id, tool, summary FROM approval WHERE chat = $c AND status = 'pending' ORDER BY id", c=cid) +def pending(db, cid, account=None): + """What waits in a conversation: what the assistant proposed there, and the automations' actions the account's + person was told about there (approvals.ask), oldest first.""" + return db.rows( + "SELECT record::id(id) AS id, tool, summary, intent FROM approval WHERE status = 'pending'" + + (" AND account = $a" if account is not None else "") + + " AND (chat = $c OR told.*.conversation CONTAINS $c) ORDER BY id", + c=cid, + a=account, + ) def decide_in_room(db, cfg, base, account, cid, m, q): - """A "yes" or "no" to what this conversation is waiting on: carried out (the ROOM_SAFE ones) or declined, and the - reply to post. None when q isn't one, or nothing waits.""" + """A "yes" or "no" to what this conversation is waiting on: carried out (the ROOM_SAFE ones, and an automation's + action that changes something inside Lens) or declined, and the reply to post. None when q isn't one, or nothing + waits. An automation's action is decided by a reply only when it is the one thing waiting here or named by its + number; one that reaches outside Lens is decided on its card in Lens.""" yes, no = YES_RX.match(q.strip()), NO_RX.match(q.strip()) if not (yes or no) or not room_approver(cfg, m): return None - waiting = pending(db, cid) + waiting = pending(db, cid, account["id"]) if not waiting: return None pick = (yes or no).group(1) + one = len(waiting) == 1 if pick and pick.lower() != "all": waiting = [a for a in waiting if a["id"] == int(pick)] if not waiting: return f"Nothing is waiting as #{pick}." + one = True elif not pick and len(waiting) > 1 and yes: # "yes" to several things is ambiguous: say which listed = "; ".join(f"#{a['id']} {a['summary']}" for a in waiting) return f"Several things are waiting: {listed}. Say “yes all” or “yes ”." @@ -423,29 +437,46 @@ def decide_in_room(db, cfg, base, account, cid, m, q): readable, editable = set(roles), {s for s in roles if auth.allows(roles, s, "editor")} who = (m.get("username") or "").strip("<> ") user = {"id": account["id"], "email": account["email"]} - lines, web = [], [] + lines, web, held = [], [], [] for a in waiting: - if yes and a["tool"] not in ROOM_SAFE: + if a.get("intent") and not one: # "no" or "all" to several: an automation's action is picked on its own + held.append(a) + continue + if yes and (a["intent"].get("effect") != "lens" if a.get("intent") else a["tool"] not in ROOM_SAFE): web.append(a) continue decision = "approve" if yes else "decline" try: with graph_history.acting(why=f"approved in a chat room by {who}" if yes else None): - out = ai_tools.approve(db, cfg, a["id"], user, editable, decision, base, account["admin"], readable) + out = ai_tools.approve(db, cfg, a["id"], user, editable, decision, base, account["admin"], readable, via="chat") except (ValueError, PermissionError, KeyError) as e: lines.append(f"Couldn't do “{a['summary']}”: {e}") continue auth.audit(db, user, "assistant.approval", f"approval:{a['id']}", {"decision": decision, "via": "chat room", "by": who, **out}) + if out.get("status") == "failed": + lines.append(f"Couldn't do “{a['summary']}”: {out.get('error')}") + continue lines.append(("Done: " if yes else "Declined: ") + a["summary"]) + if held: + listed = "; ".join(f"#{a['id']} {a['summary']}" for a in held) + lines.append(f"Still waiting, one at a time: {listed}. Say “yes ” or “no ”.") if web: lines.append(_web_line(cfg, db, cid, web)) return "\n".join(lines) def _web_line(cfg, db, cid, approvals): + """Where to decide what a reply here can't: the conversation in Lens, or an automation's action on its card.""" from app.email import app_url - return "Waiting for approval in Lens: " + "; ".join(a["summary"] for a in approvals) + f"\n{app_url(cfg, db)}/chat/{cid}" + base, out = app_url(cfg, db), [] + asked = [a for a in approvals if not a.get("intent")] + if asked: + out.append("Waiting for approval in Lens: " + "; ".join(a["summary"] for a in asked) + f"\n{base}/chat/{cid}") + for a in approvals: + if a.get("intent"): + out.append(f"Decide in Lens: {a['summary']}\n{base}/approvals?id={a['id']}") + return "\n".join(out) def reply_text(cfg, text, approvals, cid, db=None): diff --git a/fastapi_backend/app/domain/channels.py b/fastapi_backend/app/domain/channels.py index f81d07ab3..73b5a96b5 100644 --- a/fastapi_backend/app/domain/channels.py +++ b/fastapi_backend/app/domain/channels.py @@ -334,8 +334,9 @@ def where(ch, r): 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. + private chat it last had with someone it vouches for (routes()). `text` may be fn(channel, its view, its + chat_route) giving the text for that chat. 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 @@ -345,7 +346,8 @@ def tell(db, cfg, account, text, links=()): for ch, v, r in found: error = None try: - ch.send(v, r["target"], bridge.safe_links(v, db, text, links)) + said = text(ch, v, r) if callable(text) else text + ch.send(v, r["target"], bridge.safe_links(v, db, said, links)) except (ChannelError, RuntimeError, OSError, ValueError) as e: error = str(e) or type(e).__name__ failed.append({"channel": ch.key, "error": error}) diff --git a/fastapi_backend/tests/api/test_approvals_chat.py b/fastapi_backend/tests/api/test_approvals_chat.py new file mode 100644 index 000000000..572c5923f --- /dev/null +++ b/fastapi_backend/tests/api/test_approvals_chat.py @@ -0,0 +1,179 @@ +"""Deciding an automation's approval from a chat app (docs/automations.md, Approvals): a yes in the private chat the +person was told in decides an action that changes something inside Lens, when the channel lets them approve and +it's the one thing waiting there; one that reaches outside Lens is decided on its card; the assistant's own +approvals in a room work as before.""" + +from __future__ import annotations + +import pytest + +from app.domain import actions, approvals, bridge, channels, store, telegram +from tests import fake_llm, fake_telegram +from tests.api._assist import start_llm +from tests.helpers import make_user, seed + +update = fake_telegram.update + + +@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"}), "pods": store.ns_id(db, "pods")} + + +@pytest.fixture +def bot(people, db, cfg): + """The Telegram bot answering as me@x.io, letting alice in; alice has said hi privately, so that's where I'm told.""" + srv, url = fake_telegram.start() + telegram._BOTS.clear() + h = fake_telegram.Handler + cfg["telegram"] = { + **cfg["telegram"], + "enabled": True, + "api_url": url, + "token": fake_telegram.TOKEN, + "account": "me@x.io", + "users": ["alice"], + } + h.updates = [update("hi")] + channels.tick(db, cfg, cfg, "api-1", telegram.TELEGRAM) + h.sent = [] + yield h + srv.shutdown() + + +@pytest.fixture +def done(): + """Two test actions, one changing something inside Lens and one reaching other people, keeping what they did.""" + did = [] + + def perform(db, cfg, intent, user, dry): + did.append((intent["action"], intent["params"]["text"])) + return {"ok": True} + + for name, effect in (("test_tag", "lens"), ("test_post", "out")): + actions.register( + actions.ActionSpec( + name=name, + label=name, + group="Lens" if effect == "lens" else "Messages", + params={"type": "object", "properties": {"text": {"type": "string"}}}, + required=("text",), + effect=effect, + perform=perform, + describe=lambda p, n=name: f"{'Tag the asset' if n == 'test_tag' else 'Post'} “{p.get('text')}”", + ) + ) + yield did + for name in ("test_tag", "test_post"): + actions._ACTIONS.pop(name, None) + + +def intent(people, action="test_tag", n=7, text="school"): + return { + "key": f"51-n{n}", + "action": action, + "params": {"text": text}, + "effect": "lens" if action == "test_tag" else "out", + "risk": "ask", + "untrusted": True, + "spaces": [people["pods"]], + "run_as": people["me"], + "node": f"n{n}", + "automation": 4, + "run": 51, + } + + +def say(db, cfg, bot, text): + bot.sent = [] + bot.updates = [update(text)] + channels.tick(db, cfg, cfg, "api-1", telegram.TELEGRAM) + return bot.sent[-1]["text"] if bot.sent else None + + +def test_a_yes_in_my_chat_decides_an_action_inside_lens(db, cfg, people, bot, done): + aid = approvals.ask(db, cfg, intent(people)) + told = bot.sent[-1]["text"] + assert told.startswith("Automation 4 wants to tag the asset “school”. Reply “yes” to do it or “no” not to, or open ") + assert say(db, cfg, bot, "yes") == "Done: Tag the asset “school”" + assert done == [("test_tag", "school")] + a = approvals.get(db, aid) + assert a["status"] == "done" and a["decided_by"] == "me@x.io" + assert "yes" in [m["content"] for m in db.rows("SELECT content FROM chat_message WHERE role = 'user'")] + + +def test_an_action_reaching_outside_lens_is_decided_on_its_card(db, cfg, people, bot, done): + aid = approvals.ask(db, cfg, intent(people, "test_post")) + told = bot.sent[-1]["text"] + assert "Reply" not in told and told.endswith(f"/approvals?id={aid} to decide.") + said = say(db, cfg, bot, "yes") + assert said.startswith("Decide in Lens: Post “school”") and said.endswith(f"/approvals?id={aid}") + assert not done and approvals.get(db, aid)["status"] == "pending" + assert say(db, cfg, bot, "no") == "Declined: Post “school”" # declining does nothing, wherever it's said + assert approvals.get(db, aid)["status"] == "declined" and not done + + +def test_with_two_waiting_a_bare_yes_names_them_and_a_number_picks_one(db, cfg, people, bot, done): + first = approvals.ask(db, cfg, intent(people, n=1, text="one")) + assert "Reply “yes”" in bot.sent[-1]["text"] + second = approvals.ask(db, cfg, intent(people, n=2, text="two")) + assert "Reply" not in bot.sent[-1]["text"] # a bare yes would be ambiguous now + said = say(db, cfg, bot, "yes") + assert said.startswith("Several things are waiting:") and f"#{first}" in said and not done + said = say(db, cfg, bot, "yes all") # an automation's action is picked on its own + assert said.startswith("Still waiting, one at a time:") and not done + assert say(db, cfg, bot, f"yes {second}") == "Done: Tag the asset “two”" + assert done == [("test_tag", "two")] and approvals.get(db, first)["status"] == "pending" + assert say(db, cfg, bot, "yes") == "Done: Tag the asset “one”" # alone again + + +def test_a_yes_counts_only_from_someone_let_in_to_approve(db, cfg, people, bot, done): + cfg["telegram"]["approve"] = "off" + aid = approvals.ask(db, cfg, intent(people)) + assert "Reply" not in bot.sent[-1]["text"] + account = {"id": people["me"], "email": "me@x.io", "admin": False} + route = db.one("SELECT * FROM chat_route:telegram") + v = channels.view(cfg, telegram.TELEGRAM) + m = {"username": "alice", "userid": "7", "private": True} + assert bridge.decide_in_room(db, v, cfg, account, route["conversation"], m, "yes") is None + cfg["telegram"]["approve"] = "low_risk" + assert bridge.decide_in_room(db, v, cfg, account, route["conversation"], {"username": "eve"}, "yes") is None + assert bridge.decide_in_room(db, v, cfg, account, route["conversation"] + 1, m, "yes") is None # not where it told me + assert not done and approvals.get(db, aid)["status"] == "pending" + assert bridge.decide_in_room(db, v, cfg, account, route["conversation"], m, "yes") == "Done: Tag the asset “school”" + + +def test_the_assistants_own_room_approvals_work_as_before(db, cfg, people, bot, done): + route = db.one("SELECT * FROM chat_route:telegram") + aid = db.next_id("approval") + db.q( + "CREATE $r CONTENT $d", + r=store.R("approval", aid), + d={ + "chat": route["conversation"], + "account": people["me"], + "tool": "run_template", + "args": {}, + "summary": "Run notes", + "status": "pending", + }, + ) + said = say(db, cfg, bot, "yes") + assert said.startswith("Waiting for approval in Lens: Run notes") and said.endswith(f"/chat/{route['conversation']}") + assert say(db, cfg, bot, "no") == "Declined: Run notes" diff --git a/threat-model.json b/threat-model.json index f4fe54c3c..bc8561045 100644 --- a/threat-model.json +++ b/threat-model.json @@ -1039,7 +1039,7 @@ "property": "P-AUTOMATION-APPROVAL", "violation_symptom": "integrity-bypass", "severity_tier": "security", - "conditions": "an automation's action that asks first waits as an approval of the automation's person and nothing runs until they pick; approving, editing or always need them signed in (API keys, apps, MCP and the assistant only list and decline); a decision is claimed once; at most 100 wait per automation, each tells the person once, and undecided ones expire after automations.approval_days", + "conditions": "an automation's action that asks first waits as an approval of the automation's person and nothing runs until they pick; approving, editing or always need them signed in, or (approving an action inside Lens) a yes in the private chat they were told in, from someone the channel lets approve, while it is the only one waiting there or named by number (API keys, apps, MCP and the assistant only list and decline); a decision is claimed once; at most 100 wait per automation, each tells the person once, and undecided ones expire after automations.approval_days", "provenance": "documented", "source": "docs/automations.md \"Approvals\"" }, diff --git a/threat-model.md b/threat-model.md index c15dbbc58..d213336eb 100644 --- a/threat-model.md +++ b/threat-model.md @@ -516,7 +516,7 @@ Paths in the Voided by column are relative to `fastapi_backend/app/`. Searches c | P-QUERY | Cypher is read-only and runs on the caller's readable namespaces. A query stops within 3 million steps or 8 seconds; paths run up to 8 hops. Threshold: running past the budget is a bug; slow within it is not. | integrity-bypass (writes, scope); hang (budget) | security-critical (scope, writes); correctness-only (budget) | *(documented, docs/graph.md "3 million steps")* | Voided by: Admins see every namespace; write refusals — `domain/cypher.py:39`; budgets — `domain/cypher.py:35-38`. | | P-RETRIEVAL | Chat, assistant tools and MCP return only what the person can read, within the conversation's scope, and the tool loop stops at `ai.max_steps` and `ai.max_transcript_reads`. A namespace's chat completions answer from that namespace alone, with only the read tools its owners offered. | info-leak (scope); hang (caps) | security-critical (scope); correctness-only (caps) | *(documented, docs/assistant.md "limited to what the person can read")* | Voided by: Admins read everything; an admin setup conversation adds server tools and the `act` flag — `domain/ai_tools.py:287-289`; `ai.extensions: false` turns extensions off. | | P-APPROVAL | Assistant tools that change data wait for the person's approval, except notes and an admin's setup conversation. Inviting people and changing their access always wait, even there, and the assistant cannot remove an account. | integrity-bypass | security-critical | *(documented, docs/assistant.md "Approvals")* | Voided by: Admins read everything; an admin setup conversation adds server tools and the `act` flag — `domain/ai_tools.py:287-289`; `ai.extensions: false` turns extensions off. | -| P-AUTOMATION-APPROVAL | An automation's action that asks first (effect `out`, or `lens` beyond the event's own object) waits as an approval of the automation's person, and nothing runs until they pick. Approving, editing or allowing a node from now on (`always`) needs them signed in to Lens; API keys, apps, MCP and the assistant can only list and decline. A decision is claimed once (two at once can't both carry it out). At most 100 wait per automation and each tells the person once, so a flood of activities can't bury the inbox or their chat; undecided ones expire after `automations.approval_days` and nothing runs. | integrity-bypass | security-critical | *(documented, docs/automations.md "Approvals")* | Voided by: the person setting a node to `auto` (`always`, or the builder's toggle) — that node then runs without asking; an admin raising `automations.approval_days`. The summary and the message the person is told hold text the run read from outside Lens: links in it are broken up (P-INJECTION-EGRESS), and what runs is the intent the card shows. | +| P-AUTOMATION-APPROVAL | An automation's action that asks first (effect `out`, or `lens` beyond the event's own object) waits as an approval of the automation's person, and nothing runs until they pick. Approving, editing or allowing a node from now on (`always`) needs them signed in to Lens, or (approving an action that stays inside Lens, effect `lens`) a yes in the private chat Lens told them in, from someone on that channel's `users` list with approving on, while it is the only thing waiting there or named by its number; an action that reaches outside Lens is approved on its card. API keys, apps, MCP and the assistant can only list and decline. A decision is claimed once (two at once can't both carry it out). At most 100 wait per automation and each tells the person once, so a flood of activities can't bury the inbox or their chat; undecided ones expire after `automations.approval_days` and nothing runs. | integrity-bypass | security-critical | *(documented, docs/automations.md "Approvals")* | Voided by: the person setting a node to `auto` (`always`, or the builder's toggle) — that node then runs without asking; an admin raising `automations.approval_days`. The summary and the message the person is told hold text the run read from outside Lens: links in it are broken up (P-INJECTION-EGRESS), and what runs is the intent the card shows. | | P-INJECTION-EGRESS | Once an assistant answer has read text from outside Lens (a tool result other than Lens's own, the page it was asked from, a namespace assistant's memories, a message in a chat room with no `bridge.users`, or an earlier answer in the conversation that read any of these), tools that could carry it out of Lens (the person's own `read` web tools, other servers' MCP tools, Python tools with the network) and an admin setup conversation's own changes wait for the person's approval. A chat room's answer keeps a web address linkable only when the person, the archive, a tool or Lens wrote it. A bypass is `VALID-HARDENING` (Q26). An automation's model and agent actions (`ask_model`, `call_tool`, `ask_agent`) run with nobody reading along: the activity and earlier steps reach the model marked as data, every change they would make (notes included) is an approval of the automation's person, and anything that could carry data out of Lens asks first whatever the run read (docs/automations.md "The model and the agent"). | info-leak | correctness-only | *(documented, docs/assistant.md "it read out of Lens waits for your approval")* | Voided by: `ai.untrusted_asks: false` — `domain/ai_tools.py:519`; `bridge.safe_links: false` — `domain/bridge.py:298`. Notes and memories are written at once: they stay in Lens. Hooks run as their owners set them (P-EXT-SCOPE). An address the read text wrote itself stays linkable in a room. The person's browser asks first as P-BROWSER-GUARD says. | | P-EXT-SCOPE | Your own hooks run in your conversations; another person's hooks run only when an admin shared them. | integrity-bypass | security-critical | *(documented, docs/assistant.md "other people's run only when an admin shared them")* | Voided by: An admin sharing the extension — `domain/extensions.py:595-598`. | | P-NO-CODE | No non-admin can run code on the host. This covers owners, editors, viewers, API tokens, MCP agents, OAuth apps and model tool calls acting for one. Python tools are written by admins only and run only while an admin owns them. | integrity-bypass | security-critical | *(maintainer, 2026-10)* | Voided by: Making someone admin; authoring gate — `domain/extensions.py:129-130`; run gate — `domain/extensions.py:600-601`. `grep -rnE "eval\(\|exec\(\|pickle\|yaml\.load\(\|__import__" fastapi_backend/app` — one `exec`, inside the code-tool child. | diff --git a/threat-model.yaml b/threat-model.yaml index 73181c188..31781e3aa 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:13b27d6226e07e84f218d5c283b63c61b92be326a6c131ed3ec7fd95f6f6ebd2" +prose_version: "threat-model.md@sha256:49635f5cfd67e9218920c51b245a579497d5a8bc9ba8a98104676a086c28d759" model_status: under-review triage_policy: strict confidence: {documented: 201, maintainer: 46, inferred: 91, assumption: 8} @@ -1470,7 +1470,7 @@ properties_claimed: kind: integrity components: [assistant] tier: security-critical - conditions: "an automation's action that asks first waits as an approval of the automation's person and nothing runs until they pick; approving, editing or always need them signed in (API keys, apps, MCP and the assistant only list and decline); a decision is claimed once; at most 100 wait per automation, each tells the person once, and undecided ones expire after automations.approval_days" + conditions: "an automation's action that asks first waits as an approval of the automation's person and nothing runs until they pick; approving, editing or always need them signed in, or (approving an action inside Lens) a yes in the private chat they were told in, from someone the channel lets approve, while it is the only one waiting there or named by number (API keys, apps, MCP and the assistant only list and decline); a decision is claimed once; at most 100 wait per automation, each tells the person once, and undecided ones expire after automations.approval_days" violation_symptoms: [integrity-bypass] x-voided-by: "the person setting a node to auto (always, or the builder's toggle); an admin raising automations.approval_days; the summary and the message told hold outside text, with links broken up (P-INJECTION-EGRESS)" provenance: {kind: documented, source: 'docs/automations.md "Approvals"'}