Appearance
Roles, Policies & Permissions (RBAC)
Overview
ODP uses a Role-Based Access Control (RBAC) model:
- Roles — Group users and define system-level access flags.
- Policies — Define granular read/write/delete permissions on specific collections and fields.
- Permissions — Individual permission rules within a policy (collection + action + field restrictions + filter conditions).
Roles
Data Model
Table: odp_roles
| Column | Type | Description |
|---|---|---|
id | UUID | Primary key |
name | varchar | Display name |
icon | varchar | UI icon name |
description | text | Role description |
parent | UUID | FK to odp_roles.id — role hierarchy (nullable) |
admin_access | boolean | Bypasses all permission checks |
tech_access | boolean | System/debug access (implies admin_access) |
app_access | boolean | Can access the app panel |
impersonate_access | boolean | Can use impersonation endpoints |
enforce_tfa | boolean | Require TFA for users in this role (read at login — see note below) |
protected | boolean | Locked default role (Administrator, Public) — cannot be deleted |
shortname | varchar(100) | Slug of the role. Slugified on write; auto-generated from name on create when omitted |
weight | integer | Escalation ceiling — see Role Weight. Default 10; the seeded Administrator role is 100 |
Access Flag Hierarchy:
tech_access → admin_access (implied)
admin_access → bypasses all RBAC checks
app_access → can log into the app panel
impersonate_access → can impersonate other usersRole Endpoints
POST /roles
Create a role. Admin only.
Request Body
json
{
"name": "Editor",
"icon": "edit",
"description": "Can create and edit content",
"app_access": true,
"admin_access": false,
"tech_access": false,
"weight": 20
}weight defaults to 10 when omitted or null. The request is rejected with 403 if weight is above the caller's own role weight (see Role Weight).
Response 200
json
{ "data": "role-uuid" }GET /roles
List all roles.
Auth required: Yes
Supports standard query system.
GET /roles/:id
Read a single role.
PATCH /roles/:id
Update a role. Admin only. Subject to the role weight guard: the caller cannot update a role that sits above their own weight, nor raise any role's weight above their own.
DELETE /roles/:id
Delete a role. Admin only. Subject to the role weight guard (a role above the caller's weight cannot be deleted).
A protected role (the seeded Administrator and Public roles) cannot be deleted —
RolesServicethrows422 UnprocessableContentError(src/services/roles.ts).
Role Weight
Every role has an integer weight. It is the escalation ceiling: an actor may only assign, create or manage roles (and users holding them) whose weight is less than or equal to the weight of the actor's own primary role (accountability.role). Source: service/api/src/permissions/role-weight.ts.
- New roles get
weight: 10— the column default (migration025-roles-shortname-weight.ts) and theRolesService.createOnedefault when the payload omits it or sendsnull. - The seeded Administrator role (
protected: true+admin_access: true) is raised to100by migration091-administrator-role-weight.ts, so no custom role at the default weight can grant or manage it. - An actor with no role — or a role id that no longer exists — has weight
0. A target role with no stored weight also counts as0.
Applies to admins too
admin_access bypasses collection permissions, not the role hierarchy. A tenant admin on a role of weight 50 cannot hand out the Administrator role (100), reset an administrator's password, or edit the Administrator role.
Guarded operations
| Operation | Rule (blocked when…) | Error message |
|---|---|---|
POST /roles | payload weight (or the default 10) > actor weight | Cannot set a role weight higher than your own role |
PATCH /roles/:id | payload weight > actor weight | Cannot set a role weight higher than your own role |
PATCH /roles/:id, DELETE /roles/:id | the target role's current weight > actor weight | Cannot manage a role with a higher weight than your own role |
POST /users (single and batch create) | the role being assigned has weight > actor weight | Cannot assign a role with a higher weight than your own role |
PATCH /users/:id (and batch update) | the target user's current role weight > actor weight | Cannot manage a user whose role has a higher weight than your own role |
PATCH /users/:id with role in the payload | the new role has weight > actor weight | Cannot assign a role with a higher weight than your own role |
DELETE /users/:id (and batch delete) | the target user's current role weight > actor weight | Cannot manage a user whose role has a higher weight than your own role |
POST /users/invite | the invited role has weight > actor weight | Cannot assign a role with a higher weight than your own role |
POST /users/:id/tfa/disable | the target user's current role weight > actor weight | Cannot manage a user whose role has a higher weight than your own role |
DELETE /users/:id/providers/:linkId (unlink an SSO sign-in) | the target user's current role weight > actor weight | Cannot manage a user whose role has a higher weight than your own role |
POST /access, DELETE /access/:id (attach / detach a policy) | the target user's role weight, or the target role's weight, > actor weight | Cannot manage a user whose role has a higher weight than your own role / Cannot manage a role with a higher weight than your own role |
PATCH /settings with public_role / public_registration_role | the new role has weight > actor weight | Cannot assign a role with a higher weight than your own role |
Notes:
- Equal weight is allowed (
<=). Two roles at the same weight can manage each other. - The actor's own user row always passes the "manage user" check, so users can still update themselves. Changing your own
rolestill goes through the "assign role" check. - Service accounts are users whose role has
service_account: true, so creating or re-roling one goes through the same user checks. null/ emptyrolevalues in a payload are not checked (removing a role is not an escalation).- Deleting a protected role is refused separately with
422(see DELETE /roles/:id), even when the weight check passes.
Not restricted — internal calls. When there is no accountability or no user on it (CLI, bootstrap, SSO provisioning, self-registration via POST /users/register), the guard is skipped: the role those flows assign is configured by an admin, not chosen by the caller.
No bypass through generic writes. The guard lives in RolesService / UsersService. Generic item writes cannot reach those tables with a plain ItemsService: the /items route rejects system (odp_*) collections, and the MCP items_* tools throw 403 ("<collection>" is a system collection — use its dedicated tool). The MCP roles_* / users_* tools use the dedicated services, so they are guarded.
Error response
A blocked call returns 403 with code FORBIDDEN:
json
{
"errors": [
{
"message": "Cannot assign a role with a higher weight than your own role",
"extensions": { "code": "FORBIDDEN" }
}
]
}Example
Actor role: Tenant Admin (admin_access: true, weight: 50).
bash
# OK — 30 <= 50
POST /roles
{ "name": "Editor", "app_access": true, "weight": 30 }
# 403 — "Cannot set a role weight higher than your own role"
PATCH /roles/editor-role-uuid
{ "weight": 80 }
# 403 — "Cannot assign a role with a higher weight than your own role"
# (Administrator is weight 100)
PATCH /users/user-uuid
{ "role": "administrator-role-uuid" }
# 403 — "Cannot manage a user whose role has a higher weight than your own role"
# (target user holds the Administrator role)
PATCH /users/admin-user-uuid
{ "password": "new-password" }In the admin webapp, the role form (RoleFormModal.vue) exposes a Weight field, and the user role picker only lists roles whose weight is <= the current user's role weight (use-roles.ts), mirroring the backend guard.
Policies
Policies are named permission sets that can be attached to roles.
Data Model
Table: odp_policies
| Column | Type | Description |
|---|---|---|
id | UUID | Primary key |
name | varchar | Policy name |
icon | varchar | UI icon |
description | text | Description |
admin_access | boolean | Policy grants admin access |
app_access | boolean | Policy grants app access |
enforce_tfa | boolean | Legacy — no longer enforced. TFA enforcement moved to odp_roles.enforce_tfa (#44); the login flow reads the role, not the policy. This column is kept for backward compatibility but is not read. |
Policy Endpoints
POST /policies
Create a policy. Admin only.
json
{
"name": "Content Manager",
"description": "Full access to content collections",
"app_access": true
}GET /policies
List all policies. Supports standard query system.
GET /policies/:id
Read a single policy (with its permissions nested).
PATCH /policies/:id
Update a policy. Admin only.
DELETE /policies/:id
Delete a policy. Admin only.
Permissions
Permissions define what a policy can do on a specific collection.
Data Model
Table: odp_permissions
| Column | Type | Description |
|---|---|---|
id | integer | Primary key |
policy | UUID | FK to odp_policies.id |
collection | varchar | Collection name (e.g., articles) |
action | varchar | create, read, update, delete, share |
fields | json | Array of allowed field names (["*"] = all) |
permissions | json | Filter condition — limits which items are accessible |
validation | json | Zod-compatible validation rules for write operations |
presets | json | Default field values applied on create |
Permission Actions
| Action | Description |
|---|---|
create | Insert new items |
read | Read items (with optional row-level filter) |
update | Modify existing items |
delete | Remove items |
share | Share items publicly |
Field-Level Permissions
The fields array controls which columns are returned/writable:
json
{ "fields": ["title", "status", "published_at"] }Use ["*"] to allow all fields.
Stored formats (src/permissions/fetch-permissions.ts). fields is read as a JSON array, or as the legacy comma list title,body (a bare * = all fields). permissions and validation are read as a JSON object or null. POST/PATCH /permissions accept either form (a string is stored as it is) and refuse any other value with 400 INVALID_PAYLOAD naming the column. A stored value in no readable form (seed, migration, hand edit) makes the whole record grant nothing, and a warning names the record, its policy and the column. (Before, such a value read as null: every field, every row, or no validation.) An unreadable presets only drops the defaults.
Row-Level Permissions (Filter Conditions)
The permissions JSON uses the same filter syntax as query filters:
json
{
"permissions": {
"author_id": { "_eq": "$CURRENT_USER" }
}
}Where the permissions filter applies, by action (dynamic variables such as $CURRENT_USER are resolved in every case):
| Action | What checks the row | Filter support |
|---|---|---|
read | processAst injects it into the query (src/permissions/process-ast.ts), at every relation level | Full query filter syntax, relational keys included |
update, delete | ItemsService.verifyRowAccess counts the target keys that match it before the write; any miss answers 403 and nothing is written (batches included) | The same filter engine as read (applyFilter, src/database/ast/filter-parser.ts), relational keys included; fails closed (see below) |
create | Not applied: there is no stored row. Use validation to bound the payload | — |
A record with no permissions filter, or {}, allows every row.
Several records on one collection and action (from several policies) follow one model, the cases model: each record is a case, a filter plus a field list. A row is reachable when any record matches it, and a field shows on a row only when a record that grants the field matches that row.
| Action | Rows | Fields |
|---|---|---|
read | OR of the records' filters, at every relation level, in relational filters and in meta counts and aggregates | Per row: field f shows where a record granting f matches the row. On the other rows it reads as null (the key is present, the value is null) |
update | OR of the records' filters (ItemsService.verifyRowAccess) | Per row: each payload field must be granted by a record that matches the target row, else 403 and nothing is written |
delete | OR of the records' filters | — |
create | — (no stored row) | Union of the field lists (validateFieldAccess); every record's validation must pass (AND) |
Example: a role holds A "own items" ({ "user_created": { "_eq": "$CURRENT_USER" } }, every field) and B "published items" ({ "status": { "_eq": "published" } }, fields id, title, status) on articles, the same two records for read and update.
- It reads its own items plus every published one.
- On a published item of another author,
titleandstatusshow, andbodyisnull. - It can update
bodyon its own items only, andtitleon any row it reads.
A masked value is null for every predicate too: a filter, search, sort, groupBy or aggregate on a field sees null on the rows where the field is masked, so no query can tell the hidden value. A record without a filter (or {}) matches every row, so its fields show on every row. A single record behaves, and compiles to SQL, exactly as it did before this model.
Moving from the earlier AND model
Before this model, several read records combined with AND: a row had to match every record, and a second policy could only take rows away. Existing users therefore gain rows and lose nothing: every row they read before matched every record, so every field they saw is still shown there. On the rows they now gain, fields of records that do not match those rows are null.
Known cost on PostgreSQL
An aggregate or groupBy that reads a masked field runs over a derived table of the masked columns, and PostgreSQL then does not use a parallel aggregate. Measured on 1M rows: about 2.5–3× the unmasked aggregate (EXPLAIN ANALYZE), 5.6× at the harness p95 (service/api/test/perf/read-cases-results.md). MySQL is not affected (0.92×). Accepted 2026-11-03; a faster PostgreSQL form is in the backlog.
Update and delete filters fail closed
A filter means on update / delete what it means on read: every operator and relational path of the query filter syntax, with the same SQL. A write is refused (403, nothing written) when the filter cannot be applied as written:
- an operator or field the filter engine refuses (
_regex, an unknown operator, an unknown field); - a part that adds no condition: an empty
_and/_orarray, an empty element in it ({ "_or": [{}] }), a field with no operator ({ "status": {} }) or with a bare value ({ "status": "open" }).
A record whose whole filter is {} (or no filter) still allows every row. Each refusal is logged as a warning (Row filter ...; write refused, with the policy id when a part adds no condition), so an admin can find and fix the filter.
The validation filter is checked on the payload of create and update (validatePayload): all matching records' rules must pass (AND), and a key absent from the payload is not checked.
Query filters through a relation (validateFilterAccess): a filter that reads a related row (filter[author][email][_eq]=…) needs read on the related collection, from the same grant a fields=author.email read uses (explicit records, or the app-access synthetic grant with its row scope); that collection's rows (the OR of its records) and masks apply inside the filter. A bare foreign key (filter[author][_eq]=<id>, filter[author][_null]=true) compares the row's own column and needs only read on that column.
Dynamic variables:
$CURRENT_USER— Current user's UUID$CURRENT_ROLE— Current user's primary role UUID$CURRENT_ROLES— Array of current user's role UUIDs$CURRENT_POLICIES— Array of the current user's policy UUIDs (not available on accountability — resolves to[])$NOW— Current timestamp
Permission Endpoints
Table prefix: /permissions
POST /permissions
json
{
"policy": "policy-uuid",
"collection": "articles",
"action": "read",
"fields": ["*"],
"permissions": {
"status": { "_eq": "published" }
}
}GET /permissions
List all permissions. Admin access.
GET /permissions/me
Get all permissions applicable to the current user (resolves from roles and policies). Any authenticated user.
GET /permissions/:id
Read a single permission. Admin access.
PATCH /permissions/:id
Update a permission. Admin access.
DELETE /permissions/:id
Delete a permission. Admin access.
App-Level Permissions
Beyond collection-level RBAC, certain modules (Workflow, etc.) use app-level permissions stored in odp_app_permissions. These control access to specific module actions:
| Module | Actions |
|---|---|
workflow | view, start, participate, manage |
App permissions are checked via validateAppAccess(accountability, module, action, collection, knex) in src/permissions/index.ts.
How Permissions Are Evaluated
- Admin users (
admin_access: true) bypass all RBAC. - Tech users (
tech_access: true) implyadmin_access. - App-access synthetic grant — an
app_accessuser passesvalidateAccessfor the collections inappAccessMinimalPermissionseven with no explicit permission record, and returns before the policy system runs (src/permissions/validate-access.ts:53). That check is the action only. When the user has no explicit record, the grant's own row, field and payload scope applies downstream (getAppAccessFallbackPermission): the bullets below list the scoped collections; the others (schema metadata, translations, settings) are read-all.- #34 fail-closed own-row scoping (READ): on the read path, when an app-access user hits a user-scoped collection (activity, notifications, presets, shares, user-providers) with no explicit record,
processAstinjects the collection's own-rows filter instead of returning the whole table (src/permissions/process-ast.ts:78-87,appAccessRowScopesinsrc/permissions/app-access-permissions.ts). Global/shared collections keep read-all. - Own-row scoping (presets, WRITE): with no explicit record on
odp_presets, an app-access user reads their own rows plus shared rows (user IS NULL), but writes their own rows only. Update and delete are bound touser = $CURRENT_USER(appAccessActionRowScopes), and create and update refuse a payload whoseuseris not the caller (appAccessActionValidations), so a preset cannot be made shared or moved to another user. Sharing a preset needs an admin or an explicit policy onodp_presets. - OpenUI templates (
odp_ui_templates): with no explicit record, an app-access user reads their own rows, rows shared to their primary role ($CURRENT_ROLE, exact match: no parent or child roles), andglobalrows. They write their ownpersonalrows only: update and delete are bound touser_created = $CURRENT_USERandscope = 'personal', so an author cannot change a row once an admin shares it. Create and update refusescopeother thanpersonal, and create refuses auser_createdthat is not the caller.share_rolesis never writable and is not returned (no grant onodp_ui_templates_rolesorodp_roles);user_created,date_createdandidcannot change on update. Sharing and shared defaults are admin-only inUiTemplatesService, whatever the policies. - Owner-only collections (agentic chat history,
src/permissions/owner-only.ts):odp_ai_agentic_conversationsandodp_ai_agentic_messageshold one user's rows, owner columnuser_id. Every generic read path (ItemsService, nested relations, relational filters, counts) returns the caller's own rows only, admin and explicit policies included. Every stored record on these tables is ANDed withuser_id = $CURRENT_USER. No caller may create or update them throughItemsService; only the history service writes. An impersonation token reaches none of their rows. Without an explicit record, an app user may read both tables and delete its own conversations. This holds for every API path. In-process code (extensions, hooks) that builds services with an admin accountability is trusted and is not bound by it.
- #34 fail-closed own-row scoping (READ): on the read path, when an app-access user hits a user-scoped collection (activity, notifications, presets, shares, user-providers) with no explicit record,
- For non-admins without a synthetic grant, the service loads all policies attached to the user's roles.
- Policies are merged — if any policy grants access, the action is allowed.
- Row-level filters of several matching records are
OR-combined, on read and on update/delete (see "Several records on one collection and action" above). - A field shows, or may be updated, on a row only where a record granting it matches that row. On create, the field lists are united.
Role-Policy Assignment
Roles are linked to policies via the odp_access junction table.
Assign a policy to a role:
bash
PATCH /roles/:roleId
{
"policies": ["policy-uuid-1", "policy-uuid-2"]
}Example: Setting Up an Editor Role
bash
# 1. Create a policy
POST /policies
{
"name": "Article Editor",
"app_access": true
}
# Returns: { "data": "policy-abc" }
# 2. Add permissions to the policy
POST /permissions
{
"policy": "policy-abc",
"collection": "articles",
"action": "read",
"fields": ["*"]
}
# Update on the allowed fields, own rows only: verifyRowAccess enforces the
# filter before the write (see "Update and delete filters fail closed").
POST /permissions
{
"policy": "policy-abc",
"collection": "articles",
"action": "update",
"fields": ["title", "content", "status"],
"permissions": { "author_id": { "_eq": "$CURRENT_USER" } }
}
# 3. Create the role and assign the policy
POST /roles
{
"name": "Editor",
"app_access": true,
"policies": ["policy-abc"]
}
# 4. Assign role to user
PATCH /users/:userId
{
"role": "role-uuid"
}