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 ActionIn(l i18n.Lang, perm Permission) string
- func AgencyStrings(s Set) []string
- func DeniedMessage(perm Permission, helpers []string) string
- func DeniedText(l i18n.Lang, perm Permission, helpers []string) string
- func DescriptionIn(l i18n.Lang, p Permission) string
- func Grantable(p Permission) bool
- func GroupIn(l i18n.Lang, group string) string
- func HoldableBy(p Permission, t ActorType) bool
- func IsAgencyPermission(p Permission) bool
- func IsClientRole(key string) bool
- func IsSensitive(p Permission) bool
- func LabelIn(l i18n.Lang, p Permission) string
- func Require(p *Principal, perm Permission) error
- func RoleDescriptionIn(l i18n.Lang, key string) string
- func Valid(p Permission) bool
- type ActorType
- type AgencyRole
- type BuiltinRole
- type Def
- type DeniedError
- type EscalationError
- type Permission
- type Principal
- type Scope
- type Set
Constants ¶
const ( AgencyManagerLevel = "agency_manager" AccountManagerLevel = "account_manager" )
Agency staff levels.
const ( RoleClientApprover = "client_approver" RoleClientViewer = "client_viewer" )
Client roles: built-in in every client workspace (and only there), read only like the other built-in roles, and duplicable.
const ( RoleOwner = "owner" RoleAdmin = "admin" RoleEditor = "editor" RoleViewer = "viewer" )
Built-in role keys.
Variables ¶
var AgencyDefs = described([]Def{ {Key: AgencyView, Group: g("agency"), PeopleOnly: true}, {Key: AgencyUsage, Group: g("agency"), PeopleOnly: true}, {Key: AgencyLibrary, Group: g("agency"), PeopleOnly: true}, {Key: AgencyManage, Group: g("agency"), Sensitive: true, PeopleOnly: true}, })
AgencyDefs describes the agency permissions in display order (Instance admin and the agency's Staff screen). Group is "Agency".
var AgencyRoles = []AgencyRole{ {Key: AgencyManagerLevel, Name: "Agency manager", Description: roleAbout(AgencyManagerLevel), Permissions: AgencySet(AgencyView, AgencyUsage, AgencyLibrary, AgencyManage)}, {Key: AccountManagerLevel, Name: "Account manager", Description: roleAbout(AccountManagerLevel), Permissions: AgencySet(AgencyView, AgencyUsage, AgencyLibrary)}, }
AgencyRoles in display order. Instance admins are agency managers.
var BuiltinRoles = []BuiltinRole{ {Key: RoleOwner, Name: "Owner", Description: roleAbout(RoleOwner), Permissions: All()}, {Key: RoleAdmin, Name: "Admin", Description: roleAbout(RoleAdmin), Permissions: AllGrantable()}, {Key: RoleEditor, Name: "Editor", Description: roleAbout(RoleEditor), Permissions: NewSet(append(slices.Clone(viewAll), CampaignsEdit, CampaignsSend, CampaignsPause, TemplatesEdit, AutomationsEdit, AutomationsPublish, SubscribersCreate, SubscribersEdit, SubscribersImport, ListsManage, SegmentsEdit, FormsEdit, ReportsShare, TransactionalEdit, TransactionalPublish, AIUse, ScoringEdit, PlacementRun, GrowEdit, GrowReview, SponsorsManage, WebsiteEdit, WebsitePublish, WebsiteManage, ProductsEdit, ProductsPublish, OrdersManage, SMSSend, PushSend, WhatsAppSend)...)}, {Key: RoleViewer, Name: "Viewer", Description: roleAbout(RoleViewer), 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 ClientRoles = []BuiltinRole{ {Key: RoleClientApprover, Name: "Client approver", Description: roleAbout(RoleClientApprover), Permissions: NewSet(CampaignsView, CampaignsApprove, TemplatesView, AutomationsView, ReportsView, DeliverabilityView, SubscribersView)}, {Key: RoleClientViewer, Name: "Client viewer", Description: roleAbout(RoleClientViewer), Permissions: NewSet(CampaignsView, TemplatesView, AutomationsView, ReportsView, DeliverabilityView)}, }
ClientRoles in display order. Their permissions come from here, never from the database, like the other built-in roles.
var Defs = described([]Def{ {Key: CampaignsView, Group: g("campaigns")}, {Key: CampaignsEdit, Group: g("campaigns"), Implies: []Permission{CampaignsView}}, {Key: CampaignsSend, Group: g("campaigns"), Sensitive: true, Implies: []Permission{CampaignsView}}, {Key: CampaignsPause, Group: g("campaigns"), Implies: []Permission{CampaignsView}}, {Key: CampaignsApprove, Group: g("campaigns"), Sensitive: true, Implies: []Permission{CampaignsView}}, {Key: TemplatesView, Group: g("templates")}, {Key: TemplatesEdit, Group: g("templates"), Implies: []Permission{TemplatesView}}, {Key: TransactionalView, Group: g("transactional")}, {Key: TransactionalEdit, Group: g("transactional"), Implies: []Permission{TransactionalView}}, {Key: TransactionalPublish, Group: g("transactional"), Sensitive: true, Implies: []Permission{TransactionalView}}, {Key: TransactionalSend, Group: g("transactional"), Sensitive: true}, {Key: TransactionalContent, Group: g("transactional"), Sensitive: true, Implies: []Permission{TransactionalView}}, {Key: AutomationsView, Group: g("automations")}, {Key: AutomationsEdit, Group: g("automations"), Implies: []Permission{AutomationsView}}, {Key: AutomationsPublish, Group: g("automations"), Sensitive: true, Implies: []Permission{AutomationsView}}, {Key: SubscribersView, Group: g("contacts")}, {Key: SubscribersCreate, Group: g("contacts"), Implies: []Permission{SubscribersView}}, {Key: SubscribersEdit, Group: g("contacts"), Implies: []Permission{SubscribersView}}, {Key: SubscribersImport, Group: g("contacts"), Implies: []Permission{SubscribersView}}, {Key: SubscribersExport, Group: g("contacts"), Sensitive: true, Implies: []Permission{SubscribersView}}, {Key: SubscribersDelete, Group: g("contacts"), Sensitive: true, Implies: []Permission{SubscribersView}}, {Key: SubscribersVerify, Group: g("contacts"), Sensitive: true, NoAgents: true, Implies: []Permission{SubscribersView}}, {Key: ListsManage, Group: g("lists"), Implies: []Permission{SubscribersView}}, {Key: SegmentsEdit, Group: g("lists"), Implies: []Permission{SubscribersView}}, {Key: SegmentsSQL, Group: g("lists"), Sensitive: true, Implies: []Permission{SegmentsEdit, SubscribersView}}, {Key: FormsEdit, Group: g("forms")}, {Key: ReportsView, Group: g("reports")}, {Key: ReportsShare, Group: g("reports"), Implies: []Permission{ReportsView}}, {Key: DeliverabilityView, Group: g("deliverability")}, {Key: IntegrationsHostRepute, Group: g("deliverability"), Implies: []Permission{DeliverabilityView}}, {Key: ProvidersView, Group: g("sending")}, {Key: ProvidersManage, Group: g("sending"), Sensitive: true, Implies: []Permission{ProvidersView}}, {Key: DomainsManage, Group: g("sending"), Sensitive: true, Implies: []Permission{ProvidersView}}, {Key: TeamView, Group: g("team")}, {Key: TeamInvite, Group: g("team"), Implies: []Permission{TeamView}}, {Key: TeamManage, Group: g("team"), Sensitive: true, Implies: []Permission{TeamView, TeamInvite}}, {Key: APIKeysManage, Group: g("developer"), Sensitive: true}, {Key: WebhooksManage, Group: g("developer")}, {Key: MCPManage, Group: g("developer"), Sensitive: true}, {Key: IntegrationsView, Group: g("integrations")}, {Key: IntegrationsManage, Group: g("integrations"), Sensitive: true, PeopleOnly: true, Implies: []Permission{IntegrationsView}}, {Key: AIUse, Group: g("ai"), PeopleOnly: true}, {Key: ScoringEdit, Group: g("scoring"), Implies: []Permission{SubscribersView}}, {Key: PlacementRun, Group: g("placement"), NoAgents: true, Implies: []Permission{DeliverabilityView}}, {Key: PlacementManage, Group: g("placement"), Sensitive: true, NoAgents: true, Implies: []Permission{DeliverabilityView}}, {Key: GrowView, Group: g("grow")}, {Key: GrowEdit, Group: g("grow"), Implies: []Permission{GrowView}}, {Key: GrowReview, Group: g("grow"), Implies: []Permission{GrowView}}, {Key: GrowConnect, Group: g("grow"), Sensitive: true, Implies: []Permission{GrowView}}, {Key: EarnView, Group: g("earn")}, {Key: EarnEdit, Group: g("earn"), Sensitive: true, Implies: []Permission{EarnView}}, {Key: EarnManage, Group: g("earn"), Sensitive: true, Implies: []Permission{EarnView}}, {Key: PaymentsManage, Group: g("earn"), Sensitive: true, Implies: []Permission{EarnView}}, {Key: SponsorsManage, Group: g("earn"), Implies: []Permission{EarnView}}, {Key: ConversionsCreate, Group: g("earn")}, {Key: WebsiteView, Group: g("website")}, {Key: WebsiteEdit, Group: g("website"), Implies: []Permission{WebsiteView}}, {Key: WebsitePublish, Group: g("website"), Sensitive: true, Implies: []Permission{WebsiteView}}, {Key: WebsiteManage, Group: g("website"), Sensitive: true, Implies: []Permission{WebsiteView}}, {Key: ProductsView, Group: g("products")}, {Key: ProductsEdit, Group: g("products"), Implies: []Permission{ProductsView}}, {Key: ProductsPublish, Group: g("products"), Sensitive: true, Implies: []Permission{ProductsView}}, {Key: OrdersManage, Group: g("products"), Implies: []Permission{ProductsView}}, {Key: SMSSend, Group: g("sms"), Sensitive: true}, {Key: PushSend, Group: g("push"), Sensitive: true}, {Key: WhatsAppSend, Group: g("whatsapp"), Sensitive: true}, {Key: AuditView, Group: g("audit")}, {Key: WorkspaceManage, Group: g("workspace")}, {Key: WorkspaceTransfer, Group: g("workspace"), Sensitive: true, OwnerOnly: true}, {Key: WorkspaceDelete, Group: g("workspace"), Sensitive: true, OwnerOnly: true}, })
Defs is the catalogue of permissions in display order. Their labels and descriptions are in messages/<locale>.json (perm.<key>, perm.<key>.about).
var ErrDenied = errors.New("permission denied")
ErrDenied is wrapped by every authorization failure.
var Groups = []string{
g("campaigns"), g("templates"), g("transactional"), g("automations"), g("contacts"), g("lists"), g("forms"),
g("reports"), g("deliverability"), g("sending"), g("team"), g("developer"), g("integrations"), g("ai"),
g("scoring"), g("placement"), g("grow"), g("earn"), g("website"), g("products"), g("sms"), g("push"),
g("whatsapp"), g("audit"), g("workspace"),
}
Groups in display order.
Functions ¶
func ActionIn ¶
func ActionIn(l i18n.Lang, perm Permission) string
ActionIn is what a permission allows, as a sentence subject ("View campaigns"), in a language; "This" for a permission it doesn't know.
func AgencyStrings ¶
AgencyStrings lists the agency permissions of s as strings, in the order of AgencyDefs (Set.Strings follows the workspace catalogue, where they never appear).
func DeniedMessage ¶
func DeniedMessage(perm Permission, helpers []string) string
DeniedMessage builds "Sending needs a permission you don't have. Ask Marcus Chen or Linh Nguyen." in English; DeniedText writes it in a language.
func DeniedText ¶
func DeniedText(l i18n.Lang, perm Permission, helpers []string) string
DeniedText explains a missing permission in a language: "Sending needs a permission you don't have. Ask Marcus Chen or Linh Nguyen." Helpers are the names of members who hold it; the key itself is the problem's permission field, for API clients.
func DescriptionIn ¶
func DescriptionIn(l i18n.Lang, p Permission) string
DescriptionIn is a permission's description in a language.
func Grantable ¶
func Grantable(p Permission) bool
Grantable reports whether p may appear on a custom role, API key or agent.
func GroupIn ¶
GroupIn is a permission group's name (Def.Group, as Groups lists them) in a language: "Lists and segments".
func HoldableBy ¶
func HoldableBy(p Permission, t ActorType) bool
HoldableBy reports whether an actor of type t may hold p: people-only permissions are kept from API keys and MCP agents, and no-agents ones from MCP agents.
func IsAgencyPermission ¶
func IsAgencyPermission(p Permission) bool
IsAgencyPermission reports whether p is one of the agency permissions.
func IsClientRole ¶
IsClientRole reports whether key is one of the client roles.
func IsSensitive ¶
func IsSensitive(p Permission) bool
IsSensitive reports whether p is flagged ⚑ (two-factor policy, approvals).
func LabelIn ¶
func LabelIn(l i18n.Lang, p Permission) string
LabelIn is a permission's label in a language: "Send or schedule campaigns".
func Require ¶
func Require(p *Principal, perm Permission) error
Require returns a DeniedError when the principal lacks perm.
func RoleDescriptionIn ¶
RoleDescriptionIn is a built-in, client or agency role's description in a language, or "" for any other role.
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 AgencyRole ¶
AgencyRole is an instance-level agency role.
func Agency ¶
func Agency(level string) (AgencyRole, bool)
Agency returns the agency role with the given level.
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: one of the four, or a client role (agency.go), which only client workspaces have.
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"`
// PeopleOnly permissions are held by members only: API keys and MCP
// agents can't hold them.
PeopleOnly bool `json:"peopleOnly,omitempty"`
// NoAgents permissions can be held by members and API keys, never by
// MCP agents.
NoAgents bool `json:"noAgents,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 ( // AgencyView: the agency overview and search across your clients. AgencyView Permission = "agency:view" // AgencyUsage: usage and costs per client, rebill rates and the export. AgencyUsage Permission = "agency:usage" // AgencyLibrary: the shared library and workspace templates. AgencyLibrary Permission = "agency:library" // AgencyManage: client workspaces, staff and assignments. AgencyManage Permission = "agency:manage" )
Agency accounts (design expansion phase 8, M32; channels and agencies brief §3.10–§3.11). An agency runs one instance for its clients, each in its own workspace.
The agency permissions are instance-level: the agency roles (Agency manager, Account manager) hold them, never a workspace role, an API key or an MCP agent. They are kept out of Defs on purpose, so Valid rejects them everywhere a workspace permission is checked: the role editor, API keys and MCP agents can't be given them.
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" TransactionalView Permission = "transactional:view" TransactionalEdit Permission = "transactional:edit" TransactionalPublish Permission = "transactional:publish" TransactionalSend Permission = "transactional:send" TransactionalContent Permission = "transactional:content" 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" SubscribersVerify Permission = "subscribers:verify" 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" IntegrationsView Permission = "integrations:view" IntegrationsManage Permission = "integrations:manage" AIUse Permission = "ai:use" ScoringEdit Permission = "scoring:edit" PlacementRun Permission = "placement:run" PlacementManage Permission = "placement:manage" GrowView Permission = "grow:view" GrowEdit Permission = "grow:edit" GrowReview Permission = "grow:review" GrowConnect Permission = "grow:connect" EarnView Permission = "earn:view" EarnEdit Permission = "earn:edit" EarnManage Permission = "earn:manage" PaymentsManage Permission = "payments:manage" SponsorsManage Permission = "sponsors:manage" ConversionsCreate Permission = "conversions:create" WebsiteView Permission = "website:view" WebsiteEdit Permission = "website:edit" WebsitePublish Permission = "website:publish" WebsiteManage Permission = "website:manage" ProductsView Permission = "products:view" ProductsEdit Permission = "products:edit" ProductsPublish Permission = "products:publish" OrdersManage Permission = "orders:manage" SMSSend Permission = "sms:send" PushSend Permission = "push:send" WhatsAppSend Permission = "whatsapp:send" 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 AgencySet ¶
func AgencySet(keys ...Permission) Set
AgencySet builds a set of agency permissions. NewSet would work too, but agency keys imply nothing and are never part of a workspace 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 ¶
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) HoldableBy ¶
HoldableBy returns the permissions of s that an actor of type t may hold.
func (Set) Missing ¶
func (s Set) Missing(want Set) []Permission
Missing returns the permissions of want that s lacks, sorted.