permissions — module 0.2

Who may do what. Publishes the PermissionService that every command built with the commands library consults. Source in modules/permissions/; the types it builds on are in the permissions library.

What it does

• Loads role assignments from the player_roles table (ClickHouseRoleStore) when a database is published; otherwise keeps them in memory and warns once.
• Publishes PermissionService in the ServiceRegistry. Commands registered through Commands get their permission condition from it automatically.
• Registers /role get <player> and /role set <player> <role> (RoleCommand).

Manifest

Field	Value
id	permissions
version	0.1.0
security class	CRITICAL — decides authority for every other module
kernel	yes (cannot be disabled by /module)
dependencies	none

Settings

None of its own. Database settings come from the data library.

Commands

Command	Permission	Notes
/role get <player>	shatterveil.role.manage	shows the role
/role set <player> <role>	shatterveil.role.manage	roles: player, moderator, admin, hermes; audit-logged as role.set

Full usage and examples: Commands › /role.

Roles

Role	Includes	Notes
player	—	Everyone. Holds shatterveil.help.use.
moderator	player	Adds shatterveil.module.view and shatterveil.admin.read
admin	moderator	Adds shatterveil.module.manage and shatterveil.role.manage
hermes	player only, plus nodes granted to it by name	Service role for the AI agent. The defaults grant it shatterveil.module.view and shatterveil.admin.read. It can never hold shatterveil.role.manage; the PermissionTable refuses it even by table edit.

The default table is PermissionTable.defaults() in the permissions library. Unknown nodes are denied.

Security

• Trusted input: nothing from clients. Player names in /role are validated (Validate.playerName) and resolved against online players only; unknown names are refused.
• Console always passes; every other sender is checked on every command execution — there are no cached "allowed" decisions per session.
• Every role change is an AUDIT event with actor, target and old/new role.

When disabled

Never at runtime (kernel). If it fails to enable, no PermissionService exists and every permission-gated command denies everybody except the console.

Tests

PermissionsModuleTest: manifest, the toggle test (service withdrawn, /role unregistered), the published service defaults, and /role set end-to-end on the Minestom test process, including the audit event and refusal of bad input and unauthorised senders.