windmill/docs/datatable-viewer-roles.md

# Data table connections and whose roles they hold

A data table under roles (Enterprise Edition) resolves a connection that names a role to that
role alone. A connection that names none is resolved from the data table's default role and the
roles of one **identity**:

| Default role | A connection naming no role holds |
|---|---|
| `admin` (until changed) | `admin`, as before identity roles existed |
| another role | that role when the identity may use it, plus **every role the identity is a tenant of** |
| none (`NO_DEFAULT_DATATABLE_ROLE`) | the identity's roles only |

The identity is the job's own, `permissioned_as`, like everything else a job reaches: the
publisher for a publisher-mode app, the owner of a schedule or trigger, whoever ran a script. It
is the job's **viewer** only for an inline runnable of a full-code app whose policy entry sets
`viewer_data_access` (`DatatableConnectAs::Viewer`). Postgres row-level security then answers per
viewer from a runnable that runs as the publisher, with nothing written in the code.

A connection left with no role at all is refused. Policies test membership, which is true for a
role's own login too, so one policy serves a named connection and an unnamed one:

```sql
CREATE POLICY emea ON orders FOR SELECT
  USING (region = 'emea' AND pg_has_role(current_user, 'sales_emea', 'member'));
```

A policy names its role as text, so renaming the role breaks it.

## Code

| Where | What |
|---|---|
| `windmill-common/src/workspaces.rs` | `DatatableAccess`, `DatatableConnectAs`, `get_datatable_resource_from_db` |
| `windmill-common/src/datatable_roles_ee.rs` | `resolve_datatable_role_connection`, `resolve_unnamed_login`, `governing_identity`, `ensure_role_set_login`, `retire_role_set_logins_of`, `sweep_unused_role_set_logins` |
| `windmill-api/src/apps.rs` | `execute_component`, which sets `job_perms.viewer_data_access` for a flagged inline runnable |
| `windmill-api-jobs/src/execution.rs` | `run_end_user_email`, where a run's viewer is recorded, and `run_inline_preview_end_user` |
| `frontend/.../raw_apps/ViewerDataAccessPopup.svelte` | the runnable setting, shown when the code reads a data table or object storage |
| `frontend/.../workspaceSettings/DataTablePermissionsButton.svelte` | the roles drawer, which warns while the default is `admin` |

## What holds it together

- **A default of `admin` is not a floor.** `admin` owns the tables and bypasses row-level
  security, so nothing could be added to it, and it is the default until someone changes it.
  Such a data table resolves exactly as it did before identity roles existed. Nothing ever sets a
  default back to `admin`: removing or deleting the default role leaves none.
- **One identity decides both the default and the added roles.** The default is held when that
  identity may use it, and the roles added are those whose tenants name that same identity. A
  job never mixes its own identity's default with its viewer's roles.
- **Connecting as the viewer is the publisher's choice, made per runnable and stored in the
  policy.** It is honored on inline runnables only, whose code is deployed with the app: a path
  runnable is someone else's script, which would read with the viewer's roles without its author
  choosing to. The server stamps `job_perms.viewer_data_access` in the transaction that pushes
  the job. Nested jobs do not inherit it; an inline preview run with the job's token
  (`run_inline/preview`, what `wmill.datatable()` uses) does, since that code is the job's own.
- **A job that connects as its viewer and has none is refused**, never resolved as the job: that
  would undo what the runnable asked for. An anonymous app viewer is the usual case.
- **No role at all is a refusal, never an empty answer.** There is no login that would read
  nothing: what a role sees is up to each table's grants and policies.
- **A set login owns what it creates.** Postgres gives a new object to `current_user`, and
  default privileges go by the creating role, so a table created over a connection that holds
  several roles belongs to that set's login: no other role or identity reaches it, and it passes
  to `custom_instance_user` when the login is swept. Unnamed connections are for rows. To create
  an object, name a role or run `SET ROLE <role>` first, which a set login may do for any role it
  holds. Migrations are not affected: one that declares no role runs as `admin`.
- **The viewer is `job_perms.end_user_email`, and nothing else.** The server records it when the
  run starts: the session behind an app request, the caller of a direct run or preview, and for a
  job started with another job's token, that job's viewer. No argument reaches it.
- **A cached result belongs to one identity, one viewer and one mode.** `cached_result_path`
  hashes the job's `permissioned_as`, its recorded viewer and `viewer_data_access` into the key,
  since a cache hit returns before any connection is resolved. Turning the setting on changes no
  code, so without the mode a result read with the app's roles would be served to the viewer.
- **Only a tenant list naming the identity counts.** A workspace admin may *use* every role,
  `admin` included. The roles added are those whose tenants name the identity (user, group,
  folder, `*`), and never `admin`.
- **One role is that role's login. Several are a login per distinct set.** `wm_set_<hash>` is a
  member of exactly those roles, with `INHERIT`; the hash is over their catalog ids, so a rename
  moves nothing and a change in someone's groups resolves them to another login instead of
  editing one. Its privileges are its memberships, so `SET ROLE` only narrows and `RESET ROLE`
  comes back to it. The prefix is reserved in `validate_role_name`.
- **A `datatable_role_set` row with a password names a login that can authenticate with it.** The
  row is written after the login exists and removed, in its own commit, before the login is
  dropped or made `NOLOGIN`. A login without a row is taken back with a new password on next use,
  and so is one whose row has an empty password: that is what a sweep leaves when it could
  neither drop a login nor let it back in, so the next sweep still finds it.
- **Set logins are bounded by use, not by the number of role combinations.** One exists only for
  a set some identity actually connected with, so there are at most as many as (identity, data
  table) pairs. `last_used_at` is recorded at most once a day, and `sweep_unused_role_set_logins`,
  run from the monitor loop, drops those unused for 30 days; a dropped one is made again on
  demand. The sweep goes by this instance's rows, never by the cluster's `wm_set_*` roles: a
  cluster can serve several Windmill instances.
- **Disabling or dropping a role retires every set login holding it.** `NOLOGIN` on a role does
  not reach a login that is a member of it.
- **Mixed fleets.** A worker or server older than v1.831 connects as the default role alone, and
  refuses a data table with no default role, whose marker it reads as a role the data table
  lacks. One from v1.831 or v1.832 adds the recorded viewer's roles to every job that has one,
  flagged or not, and the job's own roles to none.

## Trust

A job that names no role reads with its own identity's roles, the same trust as the resources and
variables it reaches: every viewer of a publisher-mode app sees what the publisher's roles see.
An inline runnable that connects as its viewer runs its publisher's code with the viewer's reach
into the data table, the same trust as an app in viewer execution mode. Naming a role in the code
pins the connection to that one role either way.