windmill/docs/operator-builder-rights.md

# Operator builder rights

Two workspace settings, `operator_settings.builder_flows` and `operator_settings.builder_apps`,
that let every operator of that workspace compose flows (and AI agents, under the flow right) and
full-code apps out of runnables that already exist. Neither lets them author backend code or run arbitrary code on a worker, the
boundary the operator role draws. The app right does let them write the app's frontend code,
which runs in the viewer's browser and is why that right rests on sandbox isolation.

They are granted **independently**, because the two are not equally verifiable. A composed flow is
checked in full server-side (`check_flow_is_composition_only` refuses everything carrying code).
A full-code app is a browser-built bundle no server-side check can read, and rests instead on
forced `sandbox` isolation plus the viewer consent prompt. An admin may reasonably want the first
without the second, so **never gate on "either"**: a gate that does authorizes the kind its
workspace never granted, which is the whole point of the split. `BuilderKind` exists to make each
call site say which one it means.

These rights are now the `compose` level of a role's `flows` and `apps` capabilities
(`docs/workspace-roles.md`): `builder_flows` / `builder_apps` in the legacy operator settings set
the `operator` role to it. Gate a write with `check_operator_can_build`, naming the `BuilderKind`:
it refuses `none` and returns the level held, and the caller MUST run the composition-only checks
below at `compose` and may skip them only at `full`. `OperatorBuilderRights::any()` is only for
surfaces that are genuinely not per-kind, such as listing drafts.

## What the check has to cover

`check_flow_is_composition_only` (`windmill-common/src/flows.rs`) walks a `FlowValue` and refuses
anything that carries code. Three of its rules exist because the obvious walk misses them:

- **`FlowScript` and any populated `modules_node` / `default_node`.** These name code hoisted into
  a `flow_node` row. Only the dependency job produces them, so an authored value carrying one
  names code stored under some other flow. The walk covers `modules`, so a node reference is a way
  past it.
- **An AI agent step's `tools`.** `ToolValue::FlowModule` wraps a whole `FlowModuleValue`, so a
  tool can be a raw script.
It also returns what a value-only walk cannot authorize, for the caller to check against its own
permissions:

- **every agent a step links**. A linked agent resolves its tools from its `ai_agent` resource at
  run time, outside this walk, so the link is allowed only to an agent the builder can read. That
  is safe because of the agent rule below: an agent's tools are either a developer's code or
  passed this same check when an operator saved them. Two things keep it safe:
  - The step's `tool_inputs` replace a tool's inputs at run time, including the ones the agent's
    author set. A builder's step may bind only the inputs the agent leaves open
    (`check_bound_agent_inputs_are_open`, on `InputTransform::is_completed`), and the flow editor
    lets a builder edit only those, showing the rest read-only. What it binds there, a `$var:` or
    a JavaScript expression included, is what its own steps may already pass a deployed runnable; an input the author set
    stays theirs. The check runs on the flow's write, so a tool or input the agent gains later is
    open to a binding written before it, like the retyped path below.
  - The worker refuses a linked path whose resource is no longer an `ai_agent`
    (`get_agent_value`). Only writes of an agent are checked, so a path retyped, or recreated as
    another type, after the link was approved would otherwise run whatever `tools` it now holds.

- **the worker tags the steps pin**, or a builder routes a job onto a privileged worker group;
- **every runnable a step references**. `script_to_payload` resolves a step's path with the root DB
  handle (`db_authed = None`) and returns the referenced runnable's `on_behalf_of`, which
  `worker_flow` then applies to the step job. So composing a path is enough to run it, and to run
  it as whoever it runs as: `validate_operator_composed_flow` re-checks each path under the
  caller's RLS. This is the general case; the one below is on top of it, not instead of it.
- **the `(path, hash)` of every version-pinned step**. A step carrying a `hash` is dispatched by
  that hash alone, with the path beside it never consulted, so a readable path paired with another
  script's hash still runs that other script.

The value is not the only code a flow carries: the schema's `x-windmill-dyn-select-code` fills its
dynamic dropdowns, run as whoever loads the form, so `validate_operator_flow` refuses it like a
step's code. A builder therefore cannot save a developer's flow that has dropdowns; its editor
still previews them through the deployed flow rather than the inline route operators are refused.
Which developer flows a builder may edit at all is left to permissions: write access to the flow
or its folder.

Call it on every write **and** every preview: `run_preview_flow_job` and
`push_flow_dependencies_job` both take a request-supplied flow value, so leaving either out makes
it the way to run what the write path refuses. A flow draft goes through `validate_operator_flow`
too: a developer who loads a builder's draft in the editor runs its code as themselves.

## Agents

An agent is an `ai_agent` resource, and operators may write resources, so the `flows` capability
is also the right to build agents. Without it a restricted role writes no agent at all. Its tools run in the
agent's own runs, which take only inputs and run what is stored, and in every flow step linking
it. So `validate_operator_agent` holds an operator's agent to the composed-flow rules by checking
its tools as the tools of a one-step flow. It is called from `resolve_agent_on_behalf_of`, which
every write of an agent's value passes through: create, update, retype, update-value and version
restore. An operator's resource draft is checked the same way when it names `ai_agent` **or** an
agent is deployed at its path, whatever type the draft names: deploying a draft from the resource
editor keeps the row's type. A draft saved before an agent is created at its path is not
re-checked when someone else deploys it. A new route that writes an agent's value must go through
that function.

The same reasoning applies to a builder-authored app, with one extra step. `execute_component`
resolves the runnable it runs on the root handle, so `validate_operator_composed_app` checks every
referenced path under the caller's RLS and refuses hub ones. For a script it checks the version a
run would pick: grants are per version, and a path reused after its versions were archived starts
with none while the archived ones keep theirs. But it has to check **two** surfaces,
because they are not the same list: the policy's `script/<path>`, `flow/<path>` and
`agent/<path>` triggerables (an agent is checked as an `ai_agent` resource the caller can read),
and the by-path entries of the app value's `runnables` map, which is what the editor resolves a
`runnable_id` against and sends. Read only that map, and refuse an entry whose `type`, `path` or
`runType` is not text.

Reading a triggerable key is not a `split_once(':')`: `execute_component` looks up
`format!("{component}:{path}")` with an unrestricted component string, so `a:b:script/x` resolves
at run time for `component = "a:b"`. Every colon is a possible split, so the check validates every
suffix that parses as a runnable rather than guessing which one a request will use.

What makes those checks bind is that **`ExecutionMode::Viewer` is refused for a builder app**. In
Viewer mode `execute_component` falls back to a default triggerable for any `script/`/`flow/`/
`agent/` path, so the policy stops being the list of what the app may invoke, and the job runs as the
*viewer*: an admin who merely opened the app would run anything in the workspace as themselves.
`Publisher`, `Guest` and `Anonymous` have no such fallback; all three run as the publisher. If you ever relax the Viewer refusal, the
deploy-time path checks above stop being an authorization boundary.

## The two raw-app deploy paths are not equivalent

`create_app_raw` / `update_app_raw` are multipart: the browser already built the bundle, and
nothing server-side compiles anything. Builders use these.

`create_app_raw_source` / `update_app_raw_source` push a bundler CLI over caller-supplied `files`
as a job **on a worker**, which is arbitrary code execution and is why they already require
`jobs:run` on top of `apps:write`. They stay closed to operators, builder rights or not. Do not
"tidy" the exception away: it costs builders nothing, because the browser and the CLI both bundle
locally and deploy through the multipart endpoints.

A builder-authored app is forced to `policy.sandbox = true`. That is what makes it safe to let an
operator publish a bundle nobody reviewed: without it the bundle runs same-origin with each
viewer's Windmill session. The same check refuses a `rawscript/<sha>` key in either triggerables
map, since that key is the deployed app's authorization to run caller-supplied `raw_code` hashing
to it. It reads the value as stored, NUL escapes stripped: a stripped NUL can turn a key it
ignored into `inlineScript`.

`update_app` takes a builder too, but settings only: the deploy panel saves a deployed full-code
app's access and frontend scopes through it with no value. It reaches the same check, so a builder
can no more switch the sandbox off there than on deploy. A change of `execution_mode` alone runs
`check_operator_composed_app` on the deployed policy under the row lock, but not the readability
check, which resolves script versions on a second pool connection. It is therefore refused when
the app runs as anyone but the builder, `wm_deployers` or not: what an app running as its builder
invokes runs as that builder, who can already run it as themselves by opening the app. It is also
refused on an app whose stored policy is not sandboxed: the check would fill in the sandbox, and a
change of the mode alone keeps every other field of the policy.

A builder's **draft** goes through the same `check_operator_composed_app` as its deploy, with
`BuilderAppWrite::Draft`: an admin may open it in the editor or deploy it as it stands, so any
rule added for deploys must hold for drafts too. Where the two differ, `write` decides: a deploy
fills in an omitted sandbox, since it stores the policy it checked, and an omitted mode inherits the
deployed one, except that `Viewer` becomes `Publisher`, while a draft skips
`triggerables_v2` and must not name another user's run identity. Every frontend writer of a
builder draft must conform the policy first with `conformBuilderAppPolicy`, since a policy loaded
from someone else's app breaks these rules: the raw-app editor component does, which covers both
the standalone editor and the AI Sessions one, and so does the AI chat.

The raw-app editor previews an app isolated only when its policy has `sandbox`, and otherwise runs
the bundle same-origin with the session of whoever opens it. A builder's draft is therefore
held to the same rule as its deploy: `update_draft` refuses one whose `policy.sandbox` is not
`true`, so whatever an admin opens of an operator's, deployed or drafted, previews isolated.
Turning the sandbox off in their own editor stays that admin's explicit choice. It also refuses
a draft naming a runnable the builder cannot read, or a hub one, like the deploy: the editor
preview runs them as whoever opens it, and admits any path for an admin. That covers the
policy's legacy `triggerables` too, `rawscript/` keys included: every deploy of a draft
carries it through untouched, so an admin deploying the draft would publish it. Its
`triggerables_v2` is not checked: every deploy of a draft rebuilds it from the runnables, the
preview never reads it, and a copy gone stale since the last deploy would otherwise block
autosave. `Viewer` mode is refused in a draft as on deploy: the deploy panel shows it as
members-only, so an admin deploying the draft would publish it unawares. The builder's editor
switches it to `Publisher` on load, since that panel offers no way out of it. A draft naming a
run identity other than its builder is refused for the same reason: a builder's own deploy resets
it, but an admin's one-click draft deploy preserves it without showing it. The builder's editor
drops another user's identity on load, which an app that user deployed carries. A builder in
`wm_deployers` is the exception: like any member, their deploy may keep another identity, which
was judged acceptable for operators in that group (WIN-2536) and is the same for composed flows.

Reading a triggerable key at every colon copies it once per colon, so the check refuses a key
over 512 bytes before splitting: a quadratic walk otherwise lets a sub-megabyte key allocate
gigabytes. A 255-character path plus a component name stays well under it.

## Billing

An operator of a builder workspace consumes a full author seat. This is the one place that reads
"either right", and deliberately so: either one makes an operator an author of deployable
artifacts, and there is no half-author, so granting both costs no more than granting one. Do not
introduce per-right pricing — it turns one boolean into a capability matrix that billing, the cap
check and the displayed count would each have to agree on.

Every count reads the role's author flag from `role_seat` through `AUTHOR_SEAT_SQL`; see
`docs/workspace-roles.md`. On cloud, `billable_seats` applies the same rule; see its doc for the
out-of-repo invoice it must match.

A role change runs `check_seat_cap_for_role_change` inside the transaction that writes it, which
prices the change by counting seats twice rather than by counting the role's members: a member who
already authors elsewhere must not be charged again. A change that adds no seat never blocks.

## Accepted risks

- A builder raw app may declare `frontend_sdk_scopes`, and `mint_raw_app_sdk_token` mints as the
  *viewer*. A consenting admin therefore hands the bundle a 12h admin-identity token within the
  curated scope list. The viewer consent prompt is the gate, shown by the editor preview as well
  as the deployed app, before any token is minted. The lever, if this is ever revisited,
  is dropping `variables:read` / `resources:read` / `jobs:run` from `FRONTEND_SDK_ALLOWED_SCOPES`
  for builder apps.
- The raw-app editor preview runs an app's runnables as whoever has the editor open, where the
  deployed app runs them as its publisher. An admin opening a builder's app in the editor lets its
  frontend code run, with the admin's rights, any runnable the builder can read. Running as the
  draft's author instead would need a preview that ignores unsaved edits to the runnable list.
- A builder may make an app public (`ExecutionMode::Anonymous`): anyone with the URL runs the
  runnables its policy names, as the builder. Refusing it is the workspace's call, through the
  `RestrictAnonymousAppDeployment` protection rule. A `Guest` app is the same with a login in
  front: anyone the instance's identity provider admits, member or not, once guest access is
  enabled. `RestrictGuestAppDeployment` refuses it.
- A builder raw app may set `allow_user_resources` on a runnable's inputs, and the bundle picks the
  `$res:` path it sends. `build_args` resolves that path as the *viewer*, with no prompt, into a
  job that runs as the builder. Getting a value out takes a guessable path and a readable script
  that returns, logs or sends its input. Developers can do the same; the lever is refusing a
  non-empty `allow_user_resources` (and `s3_inputs[].allow_user_resources`) for builders.
- A builder's delete or settings-only update reads the app's kind before the write, not under a
  lock held through it. An admin converting that app to low-code in between lets the builder's
  request land on the low-code app; the builder already has write access to its path.
- A builder's draft carries no run identity other than the builder's own, and deploying one that
  carries none makes the deployer its run identity, as any deploy does. An admin deploying such a
  draft, from the editor or Compare & Deploy, therefore publishes the builder's code running as
  that admin; the deploy is the admin's explicit act, as it is for a developer's draft.
- `operator_settings` is git-synced, so a pull can flip every operator's class in a workspace and
  the billed seat count with it.
- A builder writes JavaScript expressions: step inputs, branch predicates, `stop_after_if` and
  `suspend`. They run in QuickJS with no filesystem or network access, and forbidding them would
  leave nothing to compose with.