roles

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Register

func Register(h huma.API, s *Service)

Register adds the roles operations.

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"`
	// PendingRequests are those requests, with the rules that still match.
	PendingRequests []RoleImpactPending `json:"pendingRequests"`
	// 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"`
	// TwoFactor tells that the change makes two-factor required for them:
	// with a grace period, or already enforced by their IdP.
	TwoFactor string `json:"twoFactor,omitempty" enum:"required,idp"`
}

RoleImpactMember is a member whose access changes.

type RoleImpactPending

type RoleImpactPending struct {
	Requester string `json:"requester"`
	// Subject is the campaign, automation or website post the request is for.
	Subject string `json:"subject"`
	// StillMatches are the policy rules that keep requiring approval after
	// the change, in their short words ("audience ≥ 10,000").
	StillMatches []string `json:"stillMatches"`
}

RoleImpactPending is an approval request by a holder that stays pending when the role changes (RoleEditorStates: "Their pending request for November Product Update stays pending; the policy still matches (audience ≥ 10,000)").

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

type RoleLockedPermission struct {
	Key    string `json:"key"`
	Reason string `json:"reason"`
}

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

Create adds a custom role.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, ws *store.Workspace, id uuid.UUID) error

Delete removes a custom role that nobody holds.

func (*Service) Get

Get returns one role.

func (*Service) Impact

Impact computes who gains or loses what if the role had these permissions. Its sentences read in the request's language.

func (*Service) List

func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal) (RoleList, error)

List returns every role with its members and the permission catalogue.

func (*Service) Update

func (s *Service) Update(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, in RoleInput) error

Update changes a custom role. Built-in roles are read-only.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL