Skip to content

Self-improving AI Employees for everyone

docs: server_controlled_fields holds on every tool path

trohitg5f1bc5cac7e0
diff --git a/docs-internal/discord_service.md b/docs-internal/discord_service.md
index 405e481a..fd5a50d4 100644
--- a/docs-internal/discord_service.md
+++ b/docs-internal/discord_service.md
@@ -65,16 +65,18 @@ exists to keep them apart.
## Security invariants
-**`account_id` is stripped from model arguments.** `server_controlled_fields`
-is enforced only in `BaseNode.execute_as_tool`'s ToolNode branch; a dual-purpose
-ActionNode takes an earlier return that merges `{**node_params, **tool_args}`
-with model arguments winning (the non-`ToolNode` branch of
-[`BaseNode.execute_as_tool`](../server/services/plugin/base.py)).
-Since inbound Discord messages are the realistic source of hostile tool
-arguments and `account_id` selects which bot identity sends, `AccountScopedNode`
-in [`_base.py`](../server/nodes/discord/_base.py) removes locked fields before
-the merge. A test drives the real tool path rather than asserting the
-declaration.
+**`account_id` is stripped from model arguments.** Inbound Discord messages are
+the realistic source of hostile tool arguments and `account_id` selects which
+bot identity sends, so both nodes list it in `server_controlled_fields`. The
+framework enforces that on every tool path: in process,
+[`BaseNode.execute_as_tool`](../server/services/plugin/base.py) drops locked
+fields from the model's arguments before its `{**node_params, **tool_args}`
+merge; on Temporal, where the agent workflow has already merged the arguments,
+[`NodeExecutor`](../server/services/node_executor.py) puts back the saved value
+(or the default). `AccountScopedNode` in
+[`_base.py`](../server/nodes/discord/_base.py) strips locked fields again as
+defence in depth; it runs only in process, since the per-type activity calls
+`execute` for an ActionNode. Tests drive both paths with a hostile `account_id`.
**The interaction token never leaves the server.** It is a 15-minute bearer
credential that can post as the app, and trigger output is persisted three ways,
diff --git a/docs-internal/node-logic-flows/discord/discordSend.md b/docs-internal/node-logic-flows/discord/discordSend.md
index 6c226df2..7985ddcf 100644
--- a/docs-internal/node-logic-flows/discord/discordSend.md
+++ b/docs-internal/node-logic-flows/discord/discordSend.md
@@ -105,8 +105,9 @@ flowchart TD
- One attachment per message. Discord allows 10; multiple would need a list
param and multi-file panel support.
-- `account_id` is removed from tool arguments by `AccountScopedNode` —
- `server_controlled_fields` alone does nothing on a dual-purpose ActionNode.
+- `account_id` is in `server_controlled_fields`, which the framework enforces on
+ every tool path (`BaseNode.execute_as_tool` in process, `NodeExecutor` on
+ Temporal); `AccountScopedNode` strips it again as defence in depth.
- A 429 over ~30s raises a retryable `RuntimeError` so Temporal re-dispatches
rather than pinning a worker slot.
diff --git a/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md b/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md
index dbeea744..bdc096fb 100644
--- a/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md
+++ b/docs-internal/node-logic-flows/whatsapp_business/whatsappBusinessSend.md
@@ -137,11 +137,11 @@ flowchart TD
## Edge cases & known limits
- **`phone_number_id` is intentionally absent from `Params`.** It selects which
- business identity a message is sent *from*. On a dual-purpose `ActionNode`
- there is no way to protect a declared field: `BaseNode.execute_as_tool` sends
- `{**node_params, **tool_args}`, so model arguments win, and
- `ctx.raw["_raw_parameters"]` is that same merged dict. Sourcing it from the
- credential is the only place the model cannot reach. Locked by
+ business identity a message is sent *from*. `server_controlled_fields` would
+ keep a model-set value out on every tool path, but a dual-purpose
+ `ActionNode`'s tool schema is its whole `Params`, so a declared field would
+ still be offered to the model. Sourcing it from the credential keeps it out of
+ the schema and out of every parameter merge. Locked by
`TestModelCannotChooseTheSendingNumber`, which drives the real tool path with
a hostile value.
- The upload posts **bytes, not a file handle** — `Connection.request` replays
diff --git a/docs-internal/whatsapp_business_service.md b/docs-internal/whatsapp_business_service.md
index 235347ae..aaaefa3e 100644
--- a/docs-internal/whatsapp_business_service.md
+++ b/docs-internal/whatsapp_business_service.md
@@ -63,14 +63,15 @@ validates the WABA id at the same time, returning discovered numbers with their
There is deliberately **no `phone_number_id` parameter** on any node. It selects
which business identity a message is sent *from*, which is exactly what a prompt
-injection in an inbound message would want to set. On a dual-purpose
-`ActionNode` a declared field cannot be protected: the split-schema machinery
-(`ToolInput` / `server_controlled_fields`) is a `ToolNode` extension, and
-`BaseNode.execute_as_tool` sends `{**node_params, **tool_args}` for everything
-else — model arguments win, and `ctx.raw["_raw_parameters"]` is that same merged
-dict. Sourcing it from the credential puts it somewhere model arguments cannot
-reach. Locked by `TestModelCannotChooseTheSendingNumber`, which drives the real
-tool path with a hostile `phone_number_id`.
+injection in an inbound message would want to set. Listing a declared field in
+`server_controlled_fields` would keep the model's value out on every tool path
+(`BaseNode.execute_as_tool` in process, `NodeExecutor` on Temporal), but the
+model would still be offered the field: `ToolInput` is a `ToolNode` extension,
+so the tool schema of a dual-purpose `ActionNode` is its whole `Params`.
+Sourcing the number from the credential keeps it out of the schema, and out of
+every parameter merge as defence in depth. Locked by `TestParamsShape` and
+`TestModelCannotChooseTheSendingNumber`, which drives the real tool path with a
+hostile `phone_number_id`.
## Webhook
diff --git a/server/nodes/discord/discord_send.py b/server/nodes/discord/discord_send.py
index 8d7a073c..fa0d919f 100644
--- a/server/nodes/discord/discord_send.py
+++ b/server/nodes/discord/discord_send.py
@@ -138,8 +138,8 @@ class DiscordSendNode(AccountScopedNode):
annotations = {"destructive": False, "readonly": False, "open_world": True}
task_queue = TaskQueue.MESSAGING
usable_as_tool = True
- # Which bot sends is operator configuration, not a model decision.
- # AccountScopedNode is what enforces this on the tool path.
+ # Which bot sends is operator configuration, not a model decision: every
+ # tool path keeps it from the model (AccountScopedNode strips it again).
server_controlled_fields = frozenset({"account_id"})
approval = ApprovalSpec(
channel="Discord",
diff --git a/server/nodes/whatsapp_business/_base.py b/server/nodes/whatsapp_business/_base.py
index 3fab6cb6..18f7bac0 100644
--- a/server/nodes/whatsapp_business/_base.py
+++ b/server/nodes/whatsapp_business/_base.py
@@ -211,11 +211,10 @@ async def resolve_phone_number_id(ctx: NodeContext) -> str:
"""The business number to send from — credential-sourced only.
Deliberately takes no node-level override. This value selects which
- business identity a message is sent *from*, and on a dual-purpose
- ActionNode any declared parameter is reachable by model arguments:
- ``BaseNode.execute_as_tool`` sends ``{**node_params, **tool_args}`` for
- anything that is not a ToolNode, so the model wins. Sourcing it from the
- credential puts it somewhere model arguments cannot reach.
+ business identity a message is sent *from*. A declared parameter would
+ appear in the model's tool schema (a dual-purpose ActionNode's schema is
+ its whole Params), even locked with ``server_controlled_fields``; sourcing
+ it from the credential keeps it out of the schema and every merge.
A per-node override belongs with multi-number support, which needs the
deployed-trigger filtering that is currently deferred.
diff --git a/server/nodes/whatsapp_business/whatsapp_business_send.py b/server/nodes/whatsapp_business/whatsapp_business_send.py
index a19da99d..6e77f5bc 100644
--- a/server/nodes/whatsapp_business/whatsapp_business_send.py
+++ b/server/nodes/whatsapp_business/whatsapp_business_send.py
@@ -311,16 +311,16 @@ class WhatsAppBusinessSendParams(BaseModel):
#
# It selects which business identity a message is sent *from*, so it is
# exactly the field a prompt injection in an inbound message would want to
- # set. On a dual-purpose ActionNode there is no way to protect it: the
- # split-schema machinery (ToolInput / server_controlled_fields) is a
- # ToolNode extension, and BaseNode.execute_as_tool sends
- # ``{**node_params, **tool_args}`` for everything else -- model arguments
- # win, and ctx.raw["_raw_parameters"] is that same merged dict, so reading
- # from it protects nothing.
+ # set. Listed in server_controlled_fields, a declared field would be kept
+ # from the model on every tool path (BaseNode.execute_as_tool strips it in
+ # process; NodeExecutor restores the saved value on Temporal), but it would
+ # still appear in the tool schema: ToolInput is a ToolNode extension, so
+ # this ActionNode's schema is its whole Params, and the model would be
+ # offered a field it cannot set.
#
- # The sending number therefore comes only from the credential, where the
- # model cannot reach it. A per-node override belongs with multi-number
- # support, which is deferred.
+ # The sending number therefore comes only from the credential, which keeps
+ # it out of the schema and out of every parameter merge. A per-node
+ # override belongs with multi-number support, which is deferred.
model_config = ConfigDict(extra="ignore")
@@ -427,10 +427,10 @@ class WhatsAppBusinessSendNode(ActionNode):
)
# ToolInput / server_controlled_fields are deliberately NOT declared.
- # They are ToolNode extensions; on a dual-purpose ActionNode they are
- # silently inert (BaseNode.execute_as_tool short-circuits before reading
- # them), so declaring them would advertise a protection that does not
- # exist. Fields the model must not control are kept out of Params instead.
+ # ToolInput is a ToolNode extension; nothing reads it on an ActionNode.
+ # server_controlled_fields would work here (every tool path honours it),
+ # but no field in Params needs it: the one field the model must not
+ # control, the sending number, is kept out of Params (see above).
Params = WhatsAppBusinessSendParams
Output = WhatsAppBusinessSendOutput
diff --git a/server/tests/nodes/test_discord.py b/server/tests/nodes/test_discord.py
index 248af025..4ab3e30c 100644
--- a/server/tests/nodes/test_discord.py
+++ b/server/tests/nodes/test_discord.py
@@ -1,9 +1,8 @@
"""Contract for the Discord plugin.
-The security-relevant test is ``TestModelCannotChooseTheAccount``. On a
-dual-purpose ActionNode ``BaseNode.execute_as_tool`` merges
-``{**node_params, **tool_args}`` with model arguments winning, so the only
-thing standing between a prompt injection in an inbound Discord message and
+The security-relevant test is ``TestModelCannotChooseTheAccount``. A
+dual-purpose ActionNode's tool call merges ``{**node_params, **tool_args}``,
+so what stands between a prompt injection in an inbound Discord message and
sending as a different bot is ``server_controlled_fields``. This asserts it
actually holds through the real tool path, not just the schema.
"""
@@ -382,9 +381,9 @@ class TestToolSchema:
@pytest.mark.parametrize("node_cls", [DiscordSendNode, DiscordActionNode])
def test_locked_fields_are_stripped_from_model_arguments(self, node_cls):
- """The guarantee AccountScopedNode exists to provide, at the class
- level: every locked field must be removed from tool_args before the
- merge that would otherwise let the model win."""
+ """AccountScopedNode strips every locked field from tool_args before
+ the merge, again, behind the framework's own strip (defence in
+ depth)."""
assert node_cls.server_controlled_fields
assert node_cls.execute_as_tool is not _base.ActionNode.execute_as_tool
diff --git a/server/tests/nodes/test_whatsapp_business.py b/server/tests/nodes/test_whatsapp_business.py
index d25cef57..3b3f25c3 100644
--- a/server/tests/nodes/test_whatsapp_business.py
+++ b/server/tests/nodes/test_whatsapp_business.py
@@ -1,10 +1,9 @@
"""Contract for the official Meta WhatsApp Cloud API plugin.
The security-relevant test here is ``TestModelCannotChooseTheSendingNumber``.
-On a dual-purpose ActionNode the split-schema machinery does not apply --
-``BaseNode.execute_as_tool`` merges ``{**node_params, **tool_args}`` for
-anything that is not a ToolNode -- so the only way to keep a field away from
-the model is to keep it out of Params entirely. This asserts that holds.
+A dual-purpose ActionNode's tool schema is its whole Params, so the way to keep
+a field away from the model entirely, schema included, is to keep it out of
+Params. This asserts that holds.
"""
from __future__ import annotations
@@ -513,8 +512,9 @@ class TestParamsShape:
def test_phone_number_id_is_not_a_parameter(self):
"""It selects the business identity a message is sent FROM.
- Declaring it would make it model-settable on this node kind, so it is
- credential-sourced instead. If someone adds it back, this fails.
+ Declaring it would put it in the model's tool schema on this node
+ kind, so it is credential-sourced instead. If someone adds it back,
+ this fails.
"""
assert "phone_number_id" not in WhatsAppBusinessSendParams.model_fields