Documentation
¶
Overview ¶
Package roles implements Roles & permissions (A5 §3.6, §5.9): the four read-only built-in roles, custom roles and the impact preview shown before saving. Nobody can add a permission they don't hold.
Index ¶
- func Register(h huma.API, s *Service)
- type RoleCreated
- type RoleDetail
- type RoleImpact
- type RoleImpactInput
- type RoleImpactKey
- type RoleImpactMember
- type RoleInput
- type RoleList
- type RoleLockedPermission
- type RoleMemberRef
- type RolePathInput
- type RoleSummary
- type Service
- func (s *Service) Create(ctx context.Context, ws *store.Workspace, p *authz.Principal, in RoleInput) (RoleCreated, error)
- func (s *Service) Delete(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) Get(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (RoleDetail, error)
- func (s *Service) Impact(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (RoleImpact, error)
- func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal) (RoleList, error)
- func (s *Service) Update(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, ...) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type RoleCreated ¶
type RoleCreated struct {
ID string `json:"id"`
}
RoleCreated is returned after creating a role.
type RoleDetail ¶
type RoleDetail struct {
Role RoleSummary `json:"role"`
Permissions []access.PermissionInfo `json:"permissions"`
Groups []string `json:"groups"`
Held []string `json:"held"`
CanManage bool `json:"canManage"`
Helpers []string `json:"helpers"`
}
RoleDetail is one role for the editor.
type RoleImpact ¶
type RoleImpact struct {
Added []string `json:"added"`
Removed []string `json:"removed"`
AddedSensitive []string `json:"addedSensitive"`
RemovedSensitive []string `json:"removedSensitive"`
// Members holding the role (all of them, with what changes for each).
Members []RoleImpactMember `json:"members"`
// MembersAffected counts members whose permissions change.
MembersAffected int `json:"membersAffected"`
Keys []RoleImpactKey `json:"keys"`
APIKeys int `json:"apiKeys" doc:"API keys that lose permissions"`
Agents int `json:"agents" doc:"MCP agents that lose permissions"`
// Sensitive is "None selected · two-factor not required" or the flagged keys.
Sensitive string `json:"sensitive"`
// Approvals explains what holders can do with sends.
Approvals string `json:"approvals"`
// PendingApprovals counts approval requests by holders that stay pending.
PendingApprovals int `json:"pendingApprovals"`
// Summary is "4 members and 1 API key will lose campaigns:send." (empty without losses).
Summary string `json:"summary"`
Locked []RoleLockedPermission `json:"locked"`
// GraceDays is the two-factor grace period for new holders of ⚑ permissions.
GraceDays int `json:"graceDays"`
}
RoleImpact is the preview shown before saving.
type RoleImpactInput ¶
type RoleImpactInput struct {
RoleID string `json:"roleId,omitempty"`
Permissions []string `json:"permissions" maxItems:"100"`
}
RoleImpactInput is a proposed permission set, for a new role (no roleId) or an existing one.
type RoleImpactKey ¶
type RoleImpactKey struct {
ID string `json:"id"`
Name string `json:"name"`
Kind string `json:"kind" enum:"api_key,mcp_agent"`
Loses []string `json:"loses"`
Effect string `json:"effect"`
}
RoleImpactKey is an API key or agent whose access changes.
type RoleImpactMember ¶
type RoleImpactMember struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
AvatarColor string `json:"avatarColor"`
Gains []string `json:"gains"`
Loses []string `json:"loses"`
Effect string `json:"effect"`
}
RoleImpactMember is a member whose access changes.
type RoleInput ¶
type RoleInput struct {
Name string `json:"name" minLength:"1" maxLength:"60"`
Description string `json:"description,omitempty" maxLength:"300"`
Permissions []string `json:"permissions" maxItems:"100"`
}
RoleInput creates or updates a custom role.
type RoleList ¶
type RoleList struct {
Roles []RoleSummary `json:"roles"`
Permissions []access.PermissionInfo `json:"permissions"`
Groups []string `json:"groups"`
// Held lists the caller's permissions: only these can be granted.
Held []string `json:"held"`
CanManage bool `json:"canManage"`
// Helpers hold team:manage (for read-only explanations).
Helpers []string `json:"helpers"`
}
RoleList is the roles screen.
type RoleLockedPermission ¶
RoleLockedPermission is one the caller can't grant.
type RoleMemberRef ¶
type RoleMemberRef struct {
ID string `json:"id" doc:"Membership id"`
Name string `json:"name"`
Email string `json:"email"`
AvatarColor string `json:"avatarColor"`
Status string `json:"status" enum:"active,deactivated"`
}
RoleMemberRef is a member holding a role.
type RolePathInput ¶
type RolePathInput struct {
api.WorkspaceInput
RoleID string `path:"roleId" format:"uuid"`
}
RolePathInput is a path or query input shared by several operations.
type RoleSummary ¶
type RoleSummary struct {
ID string `json:"id"`
Key string `json:"key"`
Name string `json:"name"`
Description string `json:"description"`
Builtin bool `json:"builtin"`
Permissions []string `json:"permissions"`
Sensitive bool `json:"sensitive"`
Members []RoleMemberRef `json:"members"`
Active int `json:"active"`
Deactivated int `json:"deactivated"`
Invited int `json:"invited"`
CreatedBy string `json:"createdBy,omitempty"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
}
RoleSummary is one role in the roles list.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Now func() time.Time
}
func (*Service) Create ¶
func (s *Service) Create(ctx context.Context, ws *store.Workspace, p *authz.Principal, in RoleInput) (RoleCreated, error)
Create adds a custom role.
func (*Service) Get ¶
func (s *Service) Get(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (RoleDetail, error)
Get returns one role.
func (*Service) Impact ¶
func (s *Service) Impact(ctx context.Context, ws *store.Workspace, p *authz.Principal, in RoleImpactInput) (RoleImpact, error)
Impact computes who gains or loses what if the role had these permissions.