# Roles and permissions

Authorization combines a global role with instance membership and explicit per-user overrides. It is always enforced in backend use cases.

## Global roles

- `admin`: full system administration and implicit access to every instance.
- `user`: no instance access until membership is assigned.

There is no global manager role. `manager` is an instance membership so a person may manage Palworld, use Minecraft and have no access to Valheim.

## Instance baselines

### User

- View game name, description, artwork and safe catalog metadata.
- View public connection address and game port.
- View instance status, readiness, uptime and non-sensitive configured values.
- View player count, player list and metrics when capability and policy allow.
- Start and stop the assigned instance.
- Submit a catalog installation request.

### Manager

All user permissions plus:

- Restart and request graceful shutdown.
- Trigger a manual backup.
- Apply an administrator-allowed update.
- Edit the instance page welcome message.
- View allowed game logs.
- Send announcements and kick/ban/unban when supported.
- Manage declared mods if granted.

Restore is intentionally not included. `backup.restore` must be explicitly granted by an administrator.

### Administrator

- Manage users, global settings, channels and retention.
- Manage catalog sources, templates, modules and trust decisions.
- Create, edit, duplicate, adopt and safely delete instances.
- Assign memberships and overrides.
- Configure public address, ports, storage, resources, secrets and backup policies.
- Import at creation; restore, export and delete backups.
- Approve or refuse installation requests; approval opens a prefilled creation form and never deploys immediately.
- View audit events and perform a bounded purge.

## Stable permission identifiers

```text
instance.view
instance.start
instance.stop
instance.restart
instance.update
instance.configure
instance.delete
instance.welcome.edit
metrics.view
players.view
players.kick
players.ban
players.unban
announcements.send
logs.view
mods.manage
backup.create
backup.list
backup.export
backup.restore
backup.delete
request.create
```

Admin-only system permissions are not delegated per instance in V1.

## Evaluation algorithm

1. Deny unauthenticated or disabled users.
2. Allow global admin, subject to re-authentication requirements for critical actions.
3. Require an active membership for the target instance.
4. Start from the membership baseline.
5. Apply explicit deny overrides before explicit allows.
6. Require operation prerequisites: module capability, current state and global policy.
7. Record important allowed and denied security actions according to the audit policy.

Client-provided instance IDs, roles and permission lists are never trusted. Object lookup and permission evaluation occur in one application-layer call to prevent confused-deputy errors.

## Persistence and request workflow

Instance memberships and overrides are stored in SQLite with foreign keys to
the registered instance and local user. Removing a membership also removes its
overrides. A user can have at most one pending installation request for a given
template version; users only list their own requests, while administrators list
all requests.

Approving or refusing a request is an atomic state transition from `pending`.
Refusal requires a reason. Approval retains the requested template, optional
name, player estimate, schedule, mods flag and message for a later creation
workflow, but deliberately performs no deployment and creates no instance.

All API mutations validate the session-bound CSRF token. User creation,
membership and override changes, and request review require an administrator
authentication no older than ten minutes. Authorization failures return a
generic denial so an unassigned user cannot use object identifiers to discover
instances.

## Sensitive-action safeguards

Restore, destructive delete, membership changes, secret rotation and security configuration require recent authentication. Data removal requires separate checkboxes and typed instance-name confirmation. A manager never gains new abilities merely because a module exposes a capability.