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.
const NoSenderDomain = "."
NoSenderDomain: see NoList.
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"), Sensitive: true}, {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.
var NoList = uuid.Nil
NoList and NoSenderDomain fill a scope that allows no list, or no sender domain, at all: what is left when two scopes share none (Intersect). An empty Lists means every list, so "none" has to be a value: no list has the nil id and no sender domain is ".", so every check and every query that reads a non-empty Lists as a restriction lets nothing through, and the value survives JSON (a background job's actor keeps it).
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.
func (Scope) Intersect ¶
Intersect returns what both scopes allow: an API key's or an agent's own scope narrowed to what its creator may reach right now, since the scope checked at creation goes stale when the creator is narrowed later. Empty means everything, so an empty side keeps the other; two lists of lists that share none leave NoList, never an empty list.
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.