Permissions

Admin authorization in hs-sql-agent uses a canonical permission path + action code. The canonical path is a stable authorization resource identifier; it is not the Admin UI route or an HTTP mount path. For example, /runtime/db-management and /auth/role remain authorization identities even if navigation or controller URLs are organized differently.

The same canonical identifiers support two mutually exclusive administration authorization modes. With built-in identity, HsSqlAgent members and roles resolve permission/action templates. With host authorization, HsSqlAgent passes the requested canonical permission keys through HsSqlAgentPermissionResource.Permissions, and the host application maps those keys into its own policy model. Unless a section says otherwise, the role/template details below describe built-in identity mode.

Examples from the runtime

Authentication alone is therefore not sufficient for these operations: the required path/action pair must also resolve through the member’s roles.

Permission-action templates are authoritative

The Role API exposes a permission-action-templates inventory. Each template contains:

• a permission ID, name, and path; and
• an action ID, code, and name.

A role payload submits selections as { PermissionId, ActionId } pairs. The role service normalizes duplicates and stores only pairs that exist in the template inventory.

Roles are the assignment unit

Members are assigned roles, and roles contain permission/action selections. This separates user lifecycle from reusable access policy:

Member
  └─ Role(s)
       └─ Permission path + Action

A member may have multiple roles. Effective Admin access is the combined permission surface of those assigned roles.

Authorization changes invalidate stale state

Role edits are security-sensitive. When a role’s permissions change, the role service finds affected members, increments their security version, and executes the change through the auth runtime-state cache barrier.

This is intended to prevent a previously authenticated session from keeping stale authorization after its role definition changes.

Protected SuperUser role

SuperUser is a built-in protected role in hs-sql-agent. It cannot be edited or deleted through normal role management. This ensures the bootstrap/full-control role cannot be silently redefined into a different permission set.

Related guides

• Members & Roles — member lifecycle and role guardrails.
• Database Management — DB and semantic permission examples.
• MCP Keys — MCP credentials are a separate authorization boundary from Admin roles.
• Security Policies — runtime SQL/rate/concurrency policy managed through its own Admin permission.