Add role-based access control #17

Open
opened 2026-10-07 20:58:56 +03:00 by ars9 · 0 comments
Owner

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.
## 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.
ars9 added this to the User management milestone 2026-10-07 21:20:36 +03:00
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ars9/liqa#17