authz

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

Documentation

Overview

Package authz is ReputeCast's small, in-house authorization layer. Users, API keys and MCP agents all hold a set of permission keys (A5 §3.7) and go through the same Check. Nobody can grant a permission they don't hold.

Index

Constants

View Source
const (
	RoleOwner  = "owner"
	RoleAdmin  = "admin"
	RoleEditor = "editor"
	RoleViewer = "viewer"
)

Built-in role keys.

Variables

View Source
var BuiltinRoles = []BuiltinRole{
	{Key: RoleOwner, Name: "Owner", Description: "Everything, including transferring ownership and deleting the workspace", Permissions: All()},
	{Key: RoleAdmin, Name: "Admin", Description: "Everything except transferring ownership and deleting the workspace", Permissions: AllGrantable()},
	{Key: RoleEditor, Name: "Editor", Description: "View everything; edit campaigns, templates, automations, segments (no SQL) and forms; send, pause and publish; import contacts", Permissions: NewSet(append(slices.Clone(viewAll),
		CampaignsEdit, CampaignsSend, CampaignsPause, TemplatesEdit, AutomationsEdit, AutomationsPublish,
		SubscribersCreate, SubscribersEdit, SubscribersImport, ListsManage, SegmentsEdit, FormsEdit, ReportsShare)...)},
	{Key: RoleViewer, Name: "Viewer", Description: "Read-only. Never sees secrets", Permissions: NewSet(viewAll...)},
}

BuiltinRoles in display order. Their permissions always come from here, never from the database, so upgrades can add permissions to them.

View Source
var Defs = []Def{
	{Key: CampaignsView, Group: "Campaigns", Label: "View campaigns", Description: "See campaigns, their content, audience and status."},
	{Key: CampaignsEdit, Group: "Campaigns", Label: "Edit campaigns", Description: "Create and edit drafts, request approval.", Implies: []Permission{CampaignsView}},
	{Key: CampaignsSend, Group: "Campaigns", Label: "Send or schedule campaigns", Description: "Start or schedule a send, and resume a paused one.", Sensitive: true, Implies: []Permission{CampaignsView}},
	{Key: CampaignsPause, Group: "Campaigns", Label: "Pause or cancel a live send", Description: "Stop a send that is running. Resuming needs campaigns:send.", Implies: []Permission{CampaignsView}},
	{Key: CampaignsApprove, Group: "Campaigns", Label: "Approve campaigns", Description: "Approve, reject or request changes on sends that need approval.", Sensitive: true, Implies: []Permission{CampaignsView}},

	{Key: TemplatesView, Group: "Templates", Label: "View templates", Description: "See saved templates and sections."},
	{Key: TemplatesEdit, Group: "Templates", Label: "Edit templates", Description: "Create, edit and delete templates and saved sections.", Implies: []Permission{TemplatesView}},

	{Key: AutomationsView, Group: "Automations", Label: "View automations", Description: "See flows and their live stats."},
	{Key: AutomationsEdit, Group: "Automations", Label: "Edit automations", Description: "Change drafts of flows.", Implies: []Permission{AutomationsView}},
	{Key: AutomationsPublish, Group: "Automations", Label: "Publish automations", Description: "Publish, pause and resume flows.", Sensitive: true, Implies: []Permission{AutomationsView}},

	{Key: SubscribersView, Group: "Contacts", Label: "View contacts", Description: "See contacts, profiles and activity."},
	{Key: SubscribersCreate, Group: "Contacts", Label: "Create contacts (forms and API)", Description: "Add contacts through signup forms and the API.", Implies: []Permission{SubscribersView}},
	{Key: SubscribersEdit, Group: "Contacts", Label: "Edit contacts", Description: "Change fields, tags and list membership.", Implies: []Permission{SubscribersView}},
	{Key: SubscribersImport, Group: "Contacts", Label: "Import contacts", Description: "Run the importer. Consent is always kept.", Implies: []Permission{SubscribersView}},
	{Key: SubscribersExport, Group: "Contacts", Label: "Export contacts", Description: "Download contacts. Every export is logged.", Sensitive: true, Implies: []Permission{SubscribersView}},
	{Key: SubscribersDelete, Group: "Contacts", Label: "Erase personal data", Description: "Permanently erase a contact's personal data.", Sensitive: true, Implies: []Permission{SubscribersView}},

	{Key: ListsManage, Group: "Lists and segments", Label: "Manage lists", Description: "Create, rename and delete lists.", Implies: []Permission{SubscribersView}},
	{Key: SegmentsEdit, Group: "Lists and segments", Label: "Edit segments", Description: "Build segments with the condition builder.", Implies: []Permission{SubscribersView}},
	{Key: SegmentsSQL, Group: "Lists and segments", Label: "Write SQL segments", Description: "Write read-only SQL against a contacts view.", Sensitive: true, Implies: []Permission{SegmentsEdit, SubscribersView}},

	{Key: FormsEdit, Group: "Forms and pages", Label: "Edit forms and public pages", Description: "Change signup forms, the preference center and the archive."},

	{Key: ReportsView, Group: "Reports", Label: "View reports", Description: "See campaign and automation reports."},
	{Key: ReportsShare, Group: "Reports", Label: "Create public read-only report links", Description: "Share a report with people outside the workspace.", Implies: []Permission{ReportsView}},

	{Key: DeliverabilityView, Group: "Deliverability", Label: "View deliverability", Description: "See domain, IP and provider health."},
	{Key: IntegrationsHostRepute, Group: "Deliverability", Label: "Connect HostRepute", Description: "Connect, reconnect or disconnect HostRepute.", Implies: []Permission{DeliverabilityView}},

	{Key: ProvidersView, Group: "Sending", Label: "View sending providers", Description: "See provider status and routing. Never credentials."},
	{Key: ProvidersManage, Group: "Sending", Label: "Manage providers, credentials, routing and failover", Description: "Connect providers, replace credentials, change routing.", Sensitive: true, Implies: []Permission{ProvidersView}},
	{Key: DomainsManage, Group: "Sending", Label: "Manage domains and senders", Description: "Add sending domains and sender identities.", Sensitive: true, Implies: []Permission{ProvidersView}},

	{Key: TeamView, Group: "Team", Label: "View the team", Description: "See members, roles and invitations."},
	{Key: TeamInvite, Group: "Team", Label: "Invite members", Description: "Invite people with roles you hold.", Implies: []Permission{TeamView}},
	{Key: TeamManage, Group: "Team", Label: "Manage roles and remove members", Description: "Change roles, deactivate and remove members.", Sensitive: true, Implies: []Permission{TeamView, TeamInvite}},

	{Key: APIKeysManage, Group: "Developer", Label: "Manage API keys", Description: "Create, rotate and revoke API keys.", Sensitive: true},
	{Key: WebhooksManage, Group: "Developer", Label: "Manage webhooks", Description: "Add webhook endpoints and see delivery logs."},
	{Key: MCPManage, Group: "Developer", Label: "Manage MCP agents", Description: "Create and revoke AI agents and see their actions.", Sensitive: true},

	{Key: AuditView, Group: "Audit", Label: "View the audit log", Description: "See who did what, when and from where."},

	{Key: WorkspaceManage, Group: "Workspace", Label: "Manage workspace settings", Description: "Name, default sender, timezone and the approval policy."},

	{Key: WorkspaceTransfer, Group: "Workspace", Label: "Transfer ownership", Description: "Make another member the Owner.", Sensitive: true, OwnerOnly: true},
	{Key: WorkspaceDelete, Group: "Workspace", Label: "Delete the workspace", Description: "Delete the workspace and everything in it.", Sensitive: true, OwnerOnly: true},
}

Defs is the catalogue of permissions in display order.

View Source
var ErrDenied = errors.New("permission denied")

ErrDenied is wrapped by every authorization failure.

View Source
var Groups = []string{
	"Campaigns", "Templates", "Automations", "Contacts", "Lists and segments",
	"Forms and pages", "Reports", "Deliverability", "Sending", "Team",
	"Developer", "Audit", "Workspace",
}

Groups in display order.

Functions

func DeniedMessage

func DeniedMessage(perm Permission, helpers []string) string

DeniedMessage builds "Sending needs the campaigns:send permission. Ask Marcus Chen or Linh Nguyen."

func Grantable

func Grantable(p Permission) bool

Grantable reports whether p may appear on a custom role, API key or agent.

func IsSensitive

func IsSensitive(p Permission) bool

IsSensitive reports whether p is flagged ⚑ (two-factor policy, approvals).

func Require

func Require(p *Principal, perm Permission) error

Require returns a DeniedError when the principal lacks perm.

func Valid

func Valid(p Permission) bool

Valid reports whether p is a known permission key.

Types

type ActorType

type ActorType string

ActorType identifies who is acting. The same values are written to the audit log's actor_type column.

const (
	ActorUser     ActorType = "user"
	ActorAPIKey   ActorType = "api_key"
	ActorMCPAgent ActorType = "mcp_agent"
	ActorSystem   ActorType = "system"
)

type BuiltinRole

type BuiltinRole struct {
	Key         string
	Name        string
	Description string
	Permissions Set
}

BuiltinRole describes one of the four read-only roles.

func Builtin

func Builtin(key string) (BuiltinRole, bool)

Builtin returns the built-in role with the given key.

type Def

type Def struct {
	Key         Permission `json:"key"`
	Group       string     `json:"group"`
	Label       string     `json:"label"`
	Description string     `json:"description"`
	Sensitive   bool       `json:"sensitive"`
	// Implies lists permissions included automatically (edit includes view).
	Implies []Permission `json:"implies,omitempty"`
	// OwnerOnly permissions can't be granted to custom roles, keys or agents.
	OwnerOnly bool `json:"ownerOnly,omitempty"`
}

Def describes a permission for the role editor and API docs.

func Lookup

func Lookup(p Permission) (Def, bool)

Lookup returns the definition of a permission key.

type DeniedError

type DeniedError struct {
	Permission Permission
	// Helpers are names of members who hold the permission.
	Helpers []string
	Message string
}

DeniedError explains a missing permission (principle 7: say why and who can help).

func (*DeniedError) Error

func (e *DeniedError) Error() string

func (*DeniedError) Unwrap

func (e *DeniedError) Unwrap() error

type EscalationError

type EscalationError struct {
	Missing []Permission
}

EscalationError lists permissions a granter tried to give away without holding them.

func (*EscalationError) Error

func (e *EscalationError) Error() string

func (*EscalationError) Unwrap

func (e *EscalationError) Unwrap() error

type Permission

type Permission string

Permission is a permission key such as "campaigns:send". The same keys are used for roles, API keys and MCP agents.

const (
	CampaignsView    Permission = "campaigns:view"
	CampaignsEdit    Permission = "campaigns:edit"
	CampaignsSend    Permission = "campaigns:send"
	CampaignsPause   Permission = "campaigns:pause"
	CampaignsApprove Permission = "campaigns:approve"

	TemplatesView Permission = "templates:view"
	TemplatesEdit Permission = "templates:edit"

	AutomationsView    Permission = "automations:view"
	AutomationsEdit    Permission = "automations:edit"
	AutomationsPublish Permission = "automations:publish"

	SubscribersView   Permission = "subscribers:view"
	SubscribersCreate Permission = "subscribers:create"
	SubscribersEdit   Permission = "subscribers:edit"
	SubscribersImport Permission = "subscribers:import"
	SubscribersExport Permission = "subscribers:export"
	SubscribersDelete Permission = "subscribers:delete"

	ListsManage  Permission = "lists:manage"
	SegmentsEdit Permission = "segments:edit"
	SegmentsSQL  Permission = "segments:sql"

	FormsEdit Permission = "forms:edit"

	ReportsView  Permission = "reports:view"
	ReportsShare Permission = "reports:share"

	DeliverabilityView     Permission = "deliverability:view"
	IntegrationsHostRepute Permission = "integrations:hostrepute"

	ProvidersView   Permission = "providers:view"
	ProvidersManage Permission = "providers:manage"
	DomainsManage   Permission = "domains:manage"

	TeamView   Permission = "team:view"
	TeamInvite Permission = "team:invite"
	TeamManage Permission = "team:manage"

	APIKeysManage  Permission = "apikeys:manage"
	WebhooksManage Permission = "webhooks:manage"
	MCPManage      Permission = "mcp:manage"

	AuditView Permission = "audit:view"

	WorkspaceManage Permission = "workspace:manage"

	// Owner-only actions. They are never grantable to custom roles, API keys
	// or agents; only the built-in Owner role holds them.
	WorkspaceTransfer Permission = "workspace:transfer"
	WorkspaceDelete   Permission = "workspace:delete"
)

Every permission ReputeCast knows, grouped as in the role editor.

type Principal

type Principal struct {
	Type ActorType
	// ID is the user id, API key id or agent id.
	ID   uuid.UUID
	Name string
	// UserID is the human behind the action: the user, or the key's creator.
	UserID          uuid.UUID
	Email           string
	WorkspaceID     uuid.UUID
	RoleKey         string
	RoleName        string
	Permissions     Set
	Scope           Scope
	IsInstanceAdmin bool
	SessionID       uuid.UUID
	// MFAVerified is true when the session passed a second factor (or SSO
	// asserted it), used by the "2FA for sensitive permissions" policy.
	MFAVerified bool
}

Principal is an authenticated actor acting inside one workspace (or at instance level when WorkspaceID is zero).

func (*Principal) Can

func (p *Principal) Can(perm Permission) bool

Can reports whether the principal holds the permission.

func (*Principal) IsHuman

func (p *Principal) IsHuman() bool

IsHuman reports whether a person (not a key or agent) is acting.

type Scope

type Scope struct {
	Lists         []uuid.UUID `json:"lists,omitempty"`
	SenderDomains []string    `json:"senderDomains,omitempty"`
}

Scope optionally restricts a member, API key or agent to some lists or sender domains ("Editor, Beta Program list only"). Empty means everything.

func (Scope) AllowsList

func (s Scope) AllowsList(id uuid.UUID) bool

AllowsList reports whether the scope includes the list.

func (Scope) AllowsLists

func (s Scope) AllowsLists(ids []uuid.UUID) bool

AllowsLists reports whether the scope includes every list in ids.

func (Scope) AllowsSenderDomain

func (s Scope) AllowsSenderDomain(domain string) bool

AllowsSenderDomain reports whether the scope includes the sender domain.

func (Scope) IsZero

func (s Scope) IsZero() bool

IsZero reports whether the scope places no restriction.

func (Scope) Within

func (s Scope) Within(parent Scope) bool

Within reports whether s is at most as broad as parent (used so API keys never get a wider scope than their creator).

type Set

type Set map[Permission]struct{}

Set is an immutable-by-convention set of permissions.

func All

func All() Set

All returns every permission (the Owner set).

func AllGrantable

func AllGrantable() Set

AllGrantable returns every permission except owner-only ones (the Admin set).

func CheckGrant

func CheckGrant(granter Set, wanted []Permission) (Set, error)

CheckGrant enforces "nobody can grant a permission they don't hold" and rejects unknown or owner-only keys. It returns the expanded set to store.

func Effective

func Effective(roleKey string, builtin bool, stored []string) Set

Effective resolves the permissions of a role: built-in roles from code, custom roles from their stored keys.

func NewSet

func NewSet(keys ...Permission) Set

NewSet builds a set from keys, expanding implied permissions.

func ParseSet

func ParseSet(keys []string) Set

ParseSet builds a set from string keys, dropping unknown ones.

func (Set) Has

func (s Set) Has(p Permission) bool

Has reports whether the set contains p.

func (Set) HasAll

func (s Set) HasAll(ps ...Permission) bool

HasAll reports whether the set contains every permission in ps.

func (Set) HasSensitive

func (s Set) HasSensitive() bool

HasSensitive reports whether the set holds any ⚑ permission.

func (Set) Intersect

func (s Set) Intersect(o Set) Set

Intersect returns the permissions present in both sets.

func (Set) Keys

func (s Set) Keys() []Permission

Keys returns the permissions in catalogue order.

func (Set) Missing

func (s Set) Missing(want Set) []Permission

Missing returns the permissions of want that s lacks, sorted.

func (Set) Strings

func (s Set) Strings() []string

Strings returns the keys as strings in catalogue order.

Jump to

Keyboard shortcuts

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