diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index b6aa76444..bb8302df6 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -395,7 +395,7 @@ export const SECTIONS: SectionSpec[] = [ label: "Automations", backend: ["events", "automations"], description: - "The stream of activities automations follow (new assets and what else happens in Lens): how often followers look for new ones, how long activities with no row of their own are kept, and how late a timer may still fire after Lens was off.", + "The stream of activities automations follow (new assets and what else happens in Lens): how often followers look for new ones, how long activities with no row of their own are kept, how long an automation’s action waits for your pick, and how late a timer may still fire after Lens was off.", }, { id: "startup", @@ -2697,6 +2697,15 @@ export const FIELDS: FieldSpec[] = [ max: 3650, hint: "Activities with no row of their own, such as an automation’s; new assets and other rows stay as long as they do", }, + { + section: "automations", + key: "approval_days", + label: "An automation’s action waits for your pick (days)", + kind: "int", + min: 1, + max: 365, + hint: "Then it expires and nothing runs; you decide in Approvals", + }, { section: "automations", key: "catch_up", diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 0a6d6d491..403b7aba5 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -23956,7 +23956,7 @@ "chats" ], "summary": "List Approvals", - "description": "Work the assistant proposed for you to approve (and what became of it), newest first.", + "description": "What waits for your pick (and what became of it), newest first: the assistant's proposals and automations'\nactions. Filter by `status` (pending is waiting), `origin` (automation or chat), one `automation` or one chat\n(`chat_id`); page with `before`.", "operationId": "list_approvals", "parameters": [ { @@ -23974,6 +23974,96 @@ ], "title": "Chat Id" } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "pending", + "running", + "done", + "failed", + "declined", + "expired" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" + } + }, + { + "name": "origin", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "automation", + "chat" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Origin" + } + }, + { + "name": "automation", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Automation" + } + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "ids below this one: the last id of the page before", + "title": "Before" + }, + "description": "ids below this one: the last id of the page before" + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 200, + "minimum": 1, + "default": 100, + "title": "Limit" + } } ], "responses": { @@ -24004,13 +24094,76 @@ } } }, + "/api/v1/approvals/count": { + "get": { + "tags": [ + "chats" + ], + "summary": "Count Approvals", + "description": "How many approvals wait for you, for the badge in the top bar.", + "operationId": "count_approvals", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApprovalCount" + } + } + } + } + } + } + }, "/api/v1/approvals/{aid}": { + "get": { + "tags": [ + "chats" + ], + "summary": "Get Approval", + "description": "One of your approvals.", + "operationId": "get_approval", + "parameters": [ + { + "name": "aid", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Aid" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Approval" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, "post": { "tags": [ "chats" ], "summary": "Decide Approval", - "description": "Approve (or run a sample of, or decline) something the assistant proposed. Each approval is decided once.", + "description": "Approve (or run a sample of, or decline) something the assistant proposed or an automation's action. Each\napproval is decided once. An automation's action can also be edited (`params`) and then carried out, or allowed\nfrom now on for that automation (`always`); approving one needs you signed in, since it's your pick: an API key\nor an app can only decline it.", "operationId": "decide_approval", "parameters": [ { @@ -30321,7 +30474,8 @@ }, "status": { "type": "string", - "title": "Status" + "title": "Status", + "description": "pending (waiting), running, done, failed, declined or expired" }, "created_at": { "anyOf": [ @@ -30336,6 +30490,124 @@ }, "result": { "title": "Result" + }, + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error" + }, + "origin": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalOrigin" + }, + { + "type": "null" + } + ], + "description": "the automation run that asked, when one did" + }, + "intent": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalIntent" + }, + { + "type": "null" + } + ], + "description": "an automation's action: what it would do" + }, + "automation": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Automation", + "description": "the automation's name" + }, + "space": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Space" + }, + "why": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalWhy" + }, + { + "type": "null" + } + ] + }, + "expires_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Expires At", + "description": "when it expires and nothing runs (automations only)" + }, + "decided_by": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Decided By" + }, + "decided_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Decided At" + }, + "told": { + "items": { + "$ref": "#/components/schemas/ApprovalTold" + }, + "type": "array", + "title": "Told", + "description": "the chats you were told in" + }, + "can": { + "anyOf": [ + { + "$ref": "#/components/schemas/ApprovalCan" + }, + { + "type": "null" + } + ] } }, "additionalProperties": true, @@ -30347,6 +30619,54 @@ ], "title": "Approval" }, + "ApprovalCan": { + "properties": { + "approve": { + "type": "boolean", + "title": "Approve", + "default": false + }, + "decline": { + "type": "boolean", + "title": "Decline", + "default": false + }, + "edit": { + "type": "boolean", + "title": "Edit", + "default": false + }, + "always": { + "type": "boolean", + "title": "Always", + "default": false + } + }, + "additionalProperties": true, + "type": "object", + "title": "ApprovalCan", + "description": "What you can do with it from where you asked: approving an automation's action is yours, signed in or in the\nchat it told you in; an API key, an app or an agent can only decline it." + }, + "ApprovalCount": { + "properties": { + "waiting": { + "type": "integer", + "title": "Waiting" + }, + "automations": { + "type": "integer", + "title": "Automations", + "description": "of them, waiting for an automation" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "waiting", + "automations" + ], + "title": "ApprovalCount" + }, "ApprovalDecision": { "properties": { "decision": { @@ -30354,16 +30674,162 @@ "enum": [ "approve", "sample", - "decline" + "decline", + "edit", + "always" ], "title": "Decision", + "description": "sample: a batch run on 3 assets first; edit: an automation's action with `params` changed, then carried out; always: carried out, and that action node of the automation runs without asking from now on (signed in only)", "default": "approve" + }, + "params": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Params", + "description": "edit: the params to change (null leaves one out)" } }, "additionalProperties": false, "type": "object", "title": "ApprovalDecision" }, + "ApprovalIntent": { + "properties": { + "action": { + "type": "string", + "title": "Action" + }, + "params": { + "additionalProperties": true, + "type": "object", + "title": "Params" + }, + "effect": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Effect" + }, + "risk": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Risk" + }, + "untrusted": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Untrusted", + "description": "its run read text from outside Lens" + }, + "node": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Node" + }, + "status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" + }, + "spaces": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Spaces" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "action" + ], + "title": "ApprovalIntent", + "description": "What an automation's action would do, as the inbox shows it (credential headers hidden)." + }, + "ApprovalOrigin": { + "properties": { + "automation": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Automation" + }, + "run": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Run" + }, + "node": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Node" + } + }, + "additionalProperties": true, + "type": "object", + "title": "ApprovalOrigin" + }, "ApprovalOutcome": { "properties": { "status": { @@ -30381,6 +30847,34 @@ ], "title": "Batch", "description": "the batch run started, for run_template" + }, + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error", + "description": "why an automation's action failed" + }, + "result": { + "title": "Result", + "description": "what an automation's action gave back" + }, + "always": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Always", + "description": "that node runs without asking from now on" } }, "additionalProperties": true, @@ -30390,6 +30884,101 @@ ], "title": "ApprovalOutcome" }, + "ApprovalTold": { + "properties": { + "channel": { + "type": "string", + "title": "Channel" + }, + "label": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Label" + }, + "chat": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Chat" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "channel" + ], + "title": "ApprovalTold" + }, + "ApprovalWhy": { + "properties": { + "activity": { + "type": "string", + "title": "Activity" + }, + "kind": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Kind" + }, + "summary": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Summary" + }, + "published": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Published" + }, + "url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Url" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "activity" + ], + "title": "ApprovalWhy", + "description": "The activity that caused it, as it was when it asked." + }, "AssistantMemory": { "properties": { "id": { diff --git a/threat-model.json b/threat-model.json index 8e9bd0477..f4fe54c3c 100644 --- a/threat-model.json +++ b/threat-model.json @@ -1035,6 +1035,14 @@ "provenance": "documented", "source": "docs/assistant.md \"Approvals\"" }, + { + "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", + "provenance": "documented", + "source": "docs/automations.md \"Approvals\"" + }, { "property": "P-INJECTION-EGRESS", "violation_symptom": "info-leak", diff --git a/threat-model.md b/threat-model.md index 5a6edd772..c15dbbc58 100644 --- a/threat-model.md +++ b/threat-model.md @@ -516,6 +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-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 237d01d42..73181c188 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:a396f25c854ef342e1d269daf00bed3ac90f3346087c8a02c56deb8875878e00" +prose_version: "threat-model.md@sha256:13b27d6226e07e84f218d5c283b63c61b92be326a6c131ed3ec7fd95f6f6ebd2" model_status: under-review triage_policy: strict confidence: {documented: 201, maintainer: 46, inferred: 91, assumption: 8} @@ -1466,6 +1466,14 @@ properties_claimed: violation_symptoms: [integrity-bypass] x-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" provenance: {kind: documented, source: 'docs/assistant.md "Approvals"'} + - id: P-AUTOMATION-APPROVAL + 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" + 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"'} - id: P-INJECTION-EGRESS kind: confidentiality components: [assistant]