Authentication (#15) only answers who the user is: every logged-in user can do everything. Add a basic role-based access control system. Each user has one or more roles, each role grants a set of operations, and every action, through both the REST API and MCP, checks that the current user has the operation it needs. Roles and role assignments are managed with CLI commands.
Requirements
Data model (entities + migration)
role
id - UUID v4 primary key
name - unique
builtIn - boolean
the usual timestamps
role_operation: (roleId, operation), unique together. operation is an operation pattern like scenario:read or scenario:*.
user_role: many-to-many between user and role. A user can have many roles.
A user's effective permissions are the union of the operation patterns of all their roles.
Permissions are resolved from the database on every request, not stored in the JWT, so role changes take effect immediately for existing tokens.
Operations
Operations are named entity:mode. The full list is defined in code, in one place:
Entity
Modes
Covers
auth
login, logout, change_password
logging in (also auth/me), logging out, changing your own password (#16)
scenario
read, create, update, delete, run, export, import
update also covers steps, attached files, scenario credential links and deleting run files; read covers versions, runs and run logs; export covers YAML and e2e test export
snippet
read, create, update, delete, export, import
read covers versions
environment
read, create, update, delete, export, import
credential
read, create, update, delete, export, import
read returns credential values, so treat it as sensitive
session
read, delete
browser
open, exec
exec runs arbitrary code (exec_code)
The generic import (POST /import, MCP import_yaml) requires <entity>:import for every entity type in the imported file.
Wildcards
Either part of an operation pattern can be *:
scenario:* - every mode of scenario
*:read - read on every entity that has it
*:* - everything
A pattern is valid only if each part is * or a known entity/mode, and it matches at least one operation in the list. Assigning an invalid pattern is rejected.
Wildcards match operations added later automatically.
Built-in roles
Both roles are created by the migration with builtIn = true. They can't be updated or deleted.
admin: *:*
nobody: auth:login, auth:logout
Role assignment
The first user created in the system (the user table is empty) always gets admin, plus any roles passed with --role.
Any other user gets the roles passed with --role, or nobody if none are given.
Users that already exist when the migration runs: the oldest one gets admin, the others get nobody.
There must always be at least one user with admin. Any change that would leave no admin is rejected.
CLI commands
All commands work against the configured database (DB_PATH) and inside the Docker container (docker compose exec liqa npm run ...), like the user:* commands from #15. On invalid input they print an error, exit with a non-zero code and change nothing.
Roles:
npm run role:create <name> [operation...] - creates a role with the given operation patterns (none if omitted). Fails if the name already exists or a pattern is invalid.
npm run role:get <name> - dump role data.
npm run role:update <name> [operation...] - replaces the role's operation patterns with the given list (an empty list removes them all). Fails for built-in roles, unknown roles and invalid patterns.
npm run role:delete <name> - deletes the role and removes it from all users. Fails for built-in roles and unknown roles.
Users:
npm run user:create [--role <name>]... - extends the command from #15 with optional, repeatable --role. An unknown role is an error and no user is created.
npm run user:list_roles <id> - lists all user roles.
Fails for an unknown user id.
npm run user:set_roles <id> [role...] - replaces the user's roles with the given list.
Fails for an unknown user id or role, or if the change would leave no admin.
An empty list removes all roles, so the user becomes nobody.
Enforcement
Checks apply to both the REST API and the MCP tools. Every MCP tool maps to an operation, e.g. run_scenario → scenario:run, export_scenario → scenario:export, exec_code → browser:exec.
REST: a decorator on each endpoint (e.g. @RequireOperation("scenario:update")) plus a global guard that runs after the authentication guard.
MCP: the same check inside the tool handler. A denied call returns an MCP tool error.
Login: after the password is verified, the user must have auth:login. Otherwise login fails and no token is issued.
auth/me requires auth:login, auth/logout requires auth:logout, and changing your own password (#16) requires auth:change_password.
Every endpoint and tool must declare its operation. Anything without one is denied, except the explicitly public endpoints from #15. A test checks that every route and MCP tool has an operation or is marked public.
An authenticated user without the required operation gets 403 (not 401, which the client treats as "not logged in").
With auth disabled (AUTH_ENABLED=false), RBAC is disabled too and everything stays open.
The scenario scheduler is not affected; it runs in-process.
Client
GET /api/v1/auth/me returns the user's roles and effective operation patterns. Pattern matching is shared logic, or reimplemented in the client with the same tests.
The UI hides or disables actions the user can't perform: navigation entries, create/edit/delete/run/import/export buttons, the change password page.
A user with only auth:* operations (e.g. nobody) sees a "no access, ask an administrator" page with a logout action.
New strings in en.json; Storybook stories for any new client/src/ui/ components.
Docs
docs/architecture.md: the RBAC model, the operations list and wildcard rules.
docs/mcp.md: MCP tools require operations, and what a denied call returns.
docs/development.md: the role:* and user:* commands, and the first-user rule.
Acceptance criteria
The migration creates admin (*:*) and nobody (auth:login, auth:logout).
The first user created gets admin, later users get nobody unless --role is given, and an unknown --role fails.
An admin user can call every endpoint and MCP tool.
A nobody user can log in, call auth/me and log out. Everything else, including changing the password, returns 403 (REST) or a tool error (MCP).
A user without auth:login (e.g. with no roles) can't log in.
Wildcards: scenario:* grants every scenario operation and nothing else; *:read grants every read and nothing else; invalid patterns (foo:read, scenario:exec) are rejected.
export and import are checked separately from read and create.
role:create, role:update and role:delete work for custom roles and fail for built-in roles, unknown roles and invalid patterns.
user:set_roles replaces a user's roles, fails for unknown users or roles, and rejects removing the last admin.
Role changes apply to existing tokens on their next request.
With auth disabled, behavior is unchanged and all existing tests pass.
The test covering every route and MCP tool passes.
Migration test (test/migrations.spec.ts) passes.
## Summary
Authentication (#15) only answers *who* the user is: every logged-in user can do everything. Add a basic role-based access control system. Each user has one or more roles, each role grants a set of operations, and every action, through both the REST API and MCP, checks that the current user has the operation it needs. Roles and role assignments are managed with CLI commands.
## Requirements
### Data model (entities + migration)
- `role`
- `id` - UUID v4 primary key
- `name` - unique
- `builtIn` - boolean
- the usual timestamps
- `role_operation`: (`roleId`, `operation`), unique together. `operation` is an operation pattern like `scenario:read` or `scenario:*`.
- `user_role`: many-to-many between `user` and `role`. A user can have many roles.
- A user's effective permissions are the union of the operation patterns of all their roles.
- Permissions are resolved from the database on every request, not stored in the JWT, so role changes take effect immediately for existing tokens.
### Operations
Operations are named `entity:mode`. The full list is defined in code, in one place:
| Entity | Modes | Covers |
|---|---|---|
| `auth` | `login`, `logout`, `change_password` | logging in (also `auth/me`), logging out, changing your own password (#16) |
| `scenario` | `read`, `create`, `update`, `delete`, `run`, `export`, `import` | `update` also covers steps, attached files, scenario credential links and deleting run files; `read` covers versions, runs and run logs; `export` covers YAML and e2e test export |
| `snippet` | `read`, `create`, `update`, `delete`, `export`, `import` | `read` covers versions |
| `environment` | `read`, `create`, `update`, `delete`, `export`, `import` | |
| `credential` | `read`, `create`, `update`, `delete`, `export`, `import` | `read` returns credential values, so treat it as sensitive |
| `session` | `read`, `delete` | |
| `browser` | `open`, `exec` | `exec` runs arbitrary code (`exec_code`) |
- The generic import (`POST /import`, MCP `import_yaml`) requires `<entity>:import` for every entity type in the imported file.
### Wildcards
- Either part of an operation pattern can be `*`:
- `scenario:*` - every mode of `scenario`
- `*:read` - `read` on every entity that has it
- `*:*` - everything
- A pattern is valid only if each part is `*` or a known entity/mode, and it matches at least one operation in the list. Assigning an invalid pattern is rejected.
- Wildcards match operations added later automatically.
### Built-in roles
Both roles are created by the migration with `builtIn = true`. They can't be updated or deleted.
- `admin`: `*:*`
- `nobody`: `auth:login`, `auth:logout`
### Role assignment
- The first user created in the system (the `user` table is empty) always gets `admin`, plus any roles passed with `--role`.
- Any other user gets the roles passed with `--role`, or `nobody` if none are given.
- Users that already exist when the migration runs: the oldest one gets `admin`, the others get `nobody`.
- There must always be at least one user with `admin`. Any change that would leave no admin is rejected.
### CLI commands
All commands work against the configured database (`DB_PATH`) and inside the Docker container (`docker compose exec liqa npm run ...`), like the `user:*` commands from #15. On invalid input they print an error, exit with a non-zero code and change nothing.
Roles:
- `npm run role:create <name> [operation...]` - creates a role with the given operation patterns (none if omitted). Fails if the name already exists or a pattern is invalid.
- `npm run role:get <name>` - dump role data.
- `npm run role:update <name> [operation...]` - replaces the role's operation patterns with the given list (an empty list removes them all). Fails for built-in roles, unknown roles and invalid patterns.
- `npm run role:delete <name>` - deletes the role and removes it from all users. Fails for built-in roles and unknown roles.
Users:
- `npm run user:create [--role <name>]...` - extends the command from #15 with optional, repeatable `--role`. An unknown role is an error and no user is created.
- `npm run user:list_roles <id>` - lists all user roles.
- Fails for an unknown user id.
- `npm run user:set_roles <id> [role...]` - replaces the user's roles with the given list.
- Fails for an unknown user id or role, or if the change would leave no admin.
- An empty list removes all roles, so the user becomes `nobody`.
### Enforcement
- Checks apply to **both** the REST API and the MCP tools. Every MCP tool maps to an operation, e.g. `run_scenario` → `scenario:run`, `export_scenario` → `scenario:export`, `exec_code` → `browser:exec`.
- REST: a decorator on each endpoint (e.g. `@RequireOperation("scenario:update")`) plus a global guard that runs after the authentication guard.
- MCP: the same check inside the tool handler. A denied call returns an MCP tool error.
- Login: after the password is verified, the user must have `auth:login`. Otherwise login fails and no token is issued.
- `auth/me` requires `auth:login`, `auth/logout` requires `auth:logout`, and changing your own password (#16) requires `auth:change_password`.
- Every endpoint and tool must declare its operation. Anything without one is denied, except the explicitly public endpoints from #15. A test checks that every route and MCP tool has an operation or is marked public.
- An authenticated user without the required operation gets `403` (not `401`, which the client treats as "not logged in").
- With auth disabled (`AUTH_ENABLED=false`), RBAC is disabled too and everything stays open.
- The scenario scheduler is not affected; it runs in-process.
### Client
- `GET /api/v1/auth/me` returns the user's roles and effective operation patterns. Pattern matching is shared logic, or reimplemented in the client with the same tests.
- The UI hides or disables actions the user can't perform: navigation entries, create/edit/delete/run/import/export buttons, the change password page.
- A user with only `auth:*` operations (e.g. `nobody`) sees a "no access, ask an administrator" page with a logout action.
- New strings in `en.json`; Storybook stories for any new `client/src/ui/` components.
### Docs
- `docs/architecture.md`: the RBAC model, the operations list and wildcard rules.
- `docs/mcp.md`: MCP tools require operations, and what a denied call returns.
- `docs/development.md`: the `role:*` and `user:*` commands, and the first-user rule.
## Acceptance criteria
- The migration creates `admin` (`*:*`) and `nobody` (`auth:login`, `auth:logout`).
- The first user created gets `admin`, later users get `nobody` unless `--role` is given, and an unknown `--role` fails.
- An `admin` user can call every endpoint and MCP tool.
- A `nobody` user can log in, call `auth/me` and log out. Everything else, including changing the password, returns `403` (REST) or a tool error (MCP).
- A user without `auth:login` (e.g. with no roles) can't log in.
- Wildcards: `scenario:*` grants every scenario operation and nothing else; `*:read` grants every `read` and nothing else; invalid patterns (`foo:read`, `scenario:exec`) are rejected.
- `export` and `import` are checked separately from `read` and `create`.
- `role:create`, `role:update` and `role:delete` work for custom roles and fail for built-in roles, unknown roles and invalid patterns.
- `user:set_roles` replaces a user's roles, fails for unknown users or roles, and rejects removing the last admin.
- Role changes apply to existing tokens on their next request.
- With auth disabled, behavior is unchanged and all existing tests pass.
- The test covering every route and MCP tool passes.
- Migration test (`test/migrations.spec.ts`) passes.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Summary
Authentication (#15) only answers who the user is: every logged-in user can do everything. Add a basic role-based access control system. Each user has one or more roles, each role grants a set of operations, and every action, through both the REST API and MCP, checks that the current user has the operation it needs. Roles and role assignments are managed with CLI commands.
Requirements
Data model (entities + migration)
roleid- UUID v4 primary keyname- uniquebuiltIn- booleanrole_operation: (roleId,operation), unique together.operationis an operation pattern likescenario:readorscenario:*.user_role: many-to-many betweenuserandrole. A user can have many roles.Operations
Operations are named
entity:mode. The full list is defined in code, in one place:authlogin,logout,change_passwordauth/me), logging out, changing your own password (#16)scenarioread,create,update,delete,run,export,importupdatealso covers steps, attached files, scenario credential links and deleting run files;readcovers versions, runs and run logs;exportcovers YAML and e2e test exportsnippetread,create,update,delete,export,importreadcovers versionsenvironmentread,create,update,delete,export,importcredentialread,create,update,delete,export,importreadreturns credential values, so treat it as sensitivesessionread,deletebrowseropen,execexecruns arbitrary code (exec_code)POST /import, MCPimport_yaml) requires<entity>:importfor every entity type in the imported file.Wildcards
*:scenario:*- every mode ofscenario*:read-readon every entity that has it*:*- everything*or a known entity/mode, and it matches at least one operation in the list. Assigning an invalid pattern is rejected.Built-in roles
Both roles are created by the migration with
builtIn = true. They can't be updated or deleted.admin:*:*nobody:auth:login,auth:logoutRole assignment
usertable is empty) always getsadmin, plus any roles passed with--role.--role, ornobodyif none are given.admin, the others getnobody.admin. Any change that would leave no admin is rejected.CLI commands
All commands work against the configured database (
DB_PATH) and inside the Docker container (docker compose exec liqa npm run ...), like theuser:*commands from #15. On invalid input they print an error, exit with a non-zero code and change nothing.Roles:
npm run role:create <name> [operation...]- creates a role with the given operation patterns (none if omitted). Fails if the name already exists or a pattern is invalid.npm run role:get <name>- dump role data.npm run role:update <name> [operation...]- replaces the role's operation patterns with the given list (an empty list removes them all). Fails for built-in roles, unknown roles and invalid patterns.npm run role:delete <name>- deletes the role and removes it from all users. Fails for built-in roles and unknown roles.Users:
npm run user:create [--role <name>]...- extends the command from #15 with optional, repeatable--role. An unknown role is an error and no user is created.npm run user:list_roles <id>- lists all user roles.npm run user:set_roles <id> [role...]- replaces the user's roles with the given list.nobody.Enforcement
run_scenario→scenario:run,export_scenario→scenario:export,exec_code→browser:exec.@RequireOperation("scenario:update")) plus a global guard that runs after the authentication guard.auth:login. Otherwise login fails and no token is issued.auth/merequiresauth:login,auth/logoutrequiresauth:logout, and changing your own password (#16) requiresauth:change_password.403(not401, which the client treats as "not logged in").AUTH_ENABLED=false), RBAC is disabled too and everything stays open.Client
GET /api/v1/auth/mereturns the user's roles and effective operation patterns. Pattern matching is shared logic, or reimplemented in the client with the same tests.auth:*operations (e.g.nobody) sees a "no access, ask an administrator" page with a logout action.en.json; Storybook stories for any newclient/src/ui/components.Docs
docs/architecture.md: the RBAC model, the operations list and wildcard rules.docs/mcp.md: MCP tools require operations, and what a denied call returns.docs/development.md: therole:*anduser:*commands, and the first-user rule.Acceptance criteria
admin(*:*) andnobody(auth:login,auth:logout).admin, later users getnobodyunless--roleis given, and an unknown--rolefails.adminuser can call every endpoint and MCP tool.nobodyuser can log in, callauth/meand log out. Everything else, including changing the password, returns403(REST) or a tool error (MCP).auth:login(e.g. with no roles) can't log in.scenario:*grants every scenario operation and nothing else;*:readgrants everyreadand nothing else; invalid patterns (foo:read,scenario:exec) are rejected.exportandimportare checked separately fromreadandcreate.role:create,role:updateandrole:deletework for custom roles and fail for built-in roles, unknown roles and invalid patterns.user:set_rolesreplaces a user's roles, fails for unknown users or roles, and rejects removing the last admin.test/migrations.spec.ts) passes.