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
- Variables
- func DeniedMessage(perm Permission, helpers []string) string
- func Grantable(p Permission) bool
- func IsSensitive(p Permission) bool
- func Require(p *Principal, perm Permission) error
- func Valid(p Permission) bool
- type ActorType
- type BuiltinRole
- type Def
- type DeniedError
- type EscalationError
- type Permission
- type Principal
- type Scope
- type Set
Constants ¶
const ( RoleOwner = "owner" RoleAdmin = "admin" RoleEditor = "editor" RoleViewer = "viewer" )
Built-in role keys.
Variables ¶
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.
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.
var ErrDenied = errors.New("permission denied")
ErrDenied is wrapped by every authorization failure.
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.
Types ¶
type ActorType ¶
type ActorType string
ActorType identifies who is acting. The same values are written to the audit log's actor_type column.
type BuiltinRole ¶
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" 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.
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 ¶
AllowsList reports whether the scope includes the list.
func (Scope) AllowsLists ¶
AllowsLists reports whether the scope includes every list in ids.
func (Scope) AllowsSenderDomain ¶
AllowsSenderDomain reports whether the scope includes the sender domain.
type Set ¶
type Set map[Permission]struct{}
Set is an immutable-by-convention set of permissions.
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 ¶
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 (Set) HasAll ¶
func (s Set) HasAll(ps ...Permission) bool
HasAll reports whether the set contains every permission in ps.
func (Set) HasSensitive ¶
HasSensitive reports whether the set holds any ⚑ permission.
func (Set) Missing ¶
func (s Set) Missing(want Set) []Permission
Missing returns the permissions of want that s lacks, sorted.