Documentation
¶
Overview ¶
Group and group-owner resource authorization (GroupPolicy, Groups::GroupOwnerPolicy).
License ownership rules, transcribed from LicensePolicy and the Licenses::* policies (app/policies/license_policy.rb, app/policies/licenses/*).
Machine ownership rules, transcribed from MachinePolicy (app/policies/machine_policy.rb) and Machines::HeartbeatPolicy (app/policies/machines/heartbeat_policy.rb).
Package access is the authorization foundation: the CE permission sets per role, the effective-permission intersection with wildcards, the principal in the request context and the Require helper scenarios call.
Package access: the per-resource ownership rules, transcribed from the reference's ApplicationPolicy subclasses (app/policies/*.rb). Every function answers the plain policy deny (the 403 with the "ensure the token or license is allowed to access all resources" reason); the permission gate (access.Require) runs before them.
Second-factor resource authorization (Users::SecondFactorPolicy).
Token resource authorization (TokenPolicy).
User resource authorization: the UserPolicy rules, expressed over the principal. Permission pre-checks (user.read etc.) run separately via Require.
Index ¶
- Constants
- Variables
- func Effective(role domain.Role, tokenPermissions []string) map[string]struct{}
- func EntitlementShow(p Principal, id uuid.UUID, entitlements map[uuid.UUID]struct{}) error
- func EntitlementWrite(p Principal) error
- func GroupLicenseShow(p Principal, license domain.License, groupOwned bool) error
- func GroupOwnersRead(p Principal, group domain.Group, memberOrOwner func(domain.Group) bool) error
- func GroupOwnersWrite(p Principal) error
- func GroupShow(p Principal, group domain.Group, memberOrOwner func(domain.Group) bool) error
- func GroupWrite(p Principal) error
- func KeyIndexPostCheck(p Principal, page []domain.Key) error
- func KeyRelationship(p Principal, key domain.Key) error
- func KeyShow(p Principal, key domain.Key) error
- func KeyWrite(p Principal, key domain.Key) error
- func LicenseAction(p Principal, license domain.License, clause string, userAttached bool) error
- func LicenseCreate(p Principal, license domain.License) error
- func LicenseDestroy(p Principal, license domain.License) error
- func LicenseEntitlementsAttach(p Principal, license domain.License) error
- func LicenseGroupUpdate(p Principal, license domain.License) error
- func LicenseIndexPostCheck(p Principal, page []domain.License, attached map[uuid.UUID]bool) error
- func LicenseOwnerUpdate(p Principal, license domain.License) error
- func LicensePolicyUpdate(p Principal, license domain.License, target domain.Policy) error
- func LicenseRelationshipShow(p Principal, license domain.License, userAttached bool) error
- func LicenseShow(p Principal, license domain.License, userAttached bool) error
- func LicenseTokenCreate(p Principal, license domain.License) error
- func LicenseTokenIndex(p Principal, license domain.License) error
- func LicenseUpdate(p Principal, license domain.License) error
- func LicenseUsageWrite(p Principal, license domain.License, action string) error
- func LicenseUsersAttach(p Principal, license domain.License) error
- func LicenseVisibleToUser(p Principal, license domain.License, userAttached bool) bool
- func MachineCheckOut(p Principal, m domain.Machine) error
- func MachineCreate(p Principal, license domain.License, licensed bool, owner uuid.NullUUID) error
- func MachineDestroy(p Principal, m domain.Machine) error
- func MachineLicenseOwnerShow(p Principal, m domain.Machine) error
- func MachinePing(p Principal, m domain.Machine) error
- func MachineProof(p Principal, m domain.Machine) error
- func MachineRelationshipUpdate(p Principal, m domain.Machine) error
- func MachineResetHeartbeat(p Principal, m domain.Machine) error
- func MachineShow(p Principal, m domain.Machine) error
- func MachineUpdate(p Principal, m domain.Machine) error
- func MachineUsageRead(p Principal, m domain.Machine) error
- func MachineVendorMetadata(p Principal, m domain.Machine, before, after map[string]any) error
- func PolicyEntitlementsWrite(p Principal, policy domain.Policy) error
- func PolicyIndexPostCheck(p Principal, page []domain.Policy, userPolicies map[uuid.UUID]struct{}, ...) error
- func PolicyPoolPop(p Principal, policy domain.Policy) error
- func PolicyPoolPostCheck(p Principal, policy domain.Policy, page []domain.Key) error
- func PolicyRelationship(p Principal, policy domain.Policy) error
- func PolicyShow(p Principal, policy domain.Policy, ownedByUser, ownedByLicense bool) error
- func PolicyWrite(p Principal, policy domain.Policy, destroy bool) error
- func ProductIndex(p Principal, allOpenOrLicensed bool) error
- func ProductMayRead(productID uuid.UUID, resource any) bool
- func ProductRelationship(p Principal, product domain.Product) error
- func ProductShow(p Principal, product domain.Product, licensedToBearer bool) error
- func ProductTokenCreate(p Principal) error
- func ProductTokenIndex(p Principal, product domain.Product) error
- func ProductTokenShow(p Principal, product domain.Product, tokenBearerID uuid.UUID) error
- func ProductWrite(p Principal, product domain.Product) error
- func ReasonLacksPermission(role domain.Role) string
- func Require(ctx context.Context, permission string) error
- func RequireBearerKind(ctx context.Context, kinds ...string) error
- func RolePermissions(role domain.Role) map[string]struct{}
- func RoleRank(r domain.Role) int
- func SecondFactorShow(p Principal, userID uuid.UUID) error
- func SecondFactorWrite(p Principal, userID uuid.UUID) error
- func SubresourceCreate(p Principal, m domain.Machine) error
- func SubresourceDestroy(p Principal, m domain.Machine) error
- func SubresourceUpdate(p Principal, m domain.Machine) error
- func TokenGenerateForUser(p Principal, user domain.User, licensedTo func() bool) error
- func TokenRegenerate(p Principal, token domain.Token, userOfProduct, licenseOfProduct func() bool) error
- func TokenRevoke(p Principal, token domain.Token, userOfProduct, licenseOfProduct func() bool) error
- func TokenScopeKind(p Principal) string
- func TokenShow(p Principal, token domain.Token, userOfProduct, licenseOfProduct func() bool) error
- func UserBan(p Principal, user domain.User) error
- func UserCreate(p Principal, accountProtected bool, role domain.Role) error
- func UserDestroy(p Principal, user domain.User) error
- func UserPasswordUpdate(p Principal, user domain.User) error
- func UserScopeKind(p Principal) string
- func UserShow(p Principal, user domain.User, teammate, licenseUser func() bool) error
- func UserUpdate(p Principal, user domain.User, role domain.Role) error
- func WebhookEndpointIndex(p Principal, page []domain.WebhookEndpoint) error
- func WebhookEndpointShow(p Principal, endpoint domain.WebhookEndpoint) error
- func WebhookEndpointWrite(p Principal, endpoint domain.WebhookEndpoint) error
- func WebhookEventIndex(p Principal, page []domain.WebhookEvent, productOf func(uuid.UUID) uuid.UUID) error
- func WebhookEventManage(p Principal) error
- func WebhookEventShow(p Principal, _ domain.WebhookEvent, productID uuid.UUID, hasEndpoint bool) error
- func Whatami(p Principal) string
- func With(ctx context.Context, p Principal) context.Context
- type Principal
Constants ¶
const ( BearerUser = "users" BearerProduct = "products" BearerLicense = "licenses" )
Bearer kinds (the wire resource types of the bearers).
const ReasonAllResources = " (ensure the token or license is allowed to access all resources)"
ReasonAllResources is the policy-deny reason appended to the 403 detail when a permission is missing.
const ReasonMustHaveUserRole = " (must have a user role)"
ReasonMustHaveUserRole is the ban/unban deny reason.
const ReasonNoCredential = " (ensure a token or license is present and valid)"
ReasonNoCredential is the policy-deny reason of an anonymous bearer.
const ReasonTokenLacksPermission = " (token lacks permission to perform action)" //nolint:gosec,lll // a policy reason, not a credential
ReasonTokenLacksPermission is the verify_permissions! reason when the bearer's role holds the permission but the token's restrictions removed it.
const VendorMetadataPrefix = "vendor_"
VendorMetadataPrefix marks the machine metadata keys only the vendor writes (a backplane extension): the values a signed machine file carries for the product to trust, such as its deadlines. Keys are stored underscored, so vendorPaymentDeadline on the wire is vendor_payment_deadline here.
Variables ¶
var AllPermissions = []string{}/* 144 elements not displayed */
AllPermissions is the full catalog of permission names (the reference's ALL_PERMISSIONS, transcribed verbatim as data).
Functions ¶
func Effective ¶
Effective computes the effective permission set of a token authentication: the intersection of the bearer's role set and the token's own permissions, where a wildcard ("*") on either side defers to the other side.
func EntitlementShow ¶
EntitlementShow mirrors EntitlementPolicy#show? (and the index post-check over a page): the admin family and the product bearer see everything; user and license bearers only their own.
func EntitlementWrite ¶
EntitlementWrite mirrors EntitlementPolicy#create?/update?/destroy?.
func GroupLicenseShow ¶
GroupLicenseShow is Groups::LicensePolicy#show?: unlike an ordinary license show, this route admits group owners without individual ownership.
func GroupOwnersRead ¶
GroupOwnersRead authorizes the owners index/show like GroupShow (membership or ownership qualifies a user bearer).
func GroupOwnersWrite ¶
GroupOwnersWrite authorizes attach/detach: admin, developer, product.
func GroupShow ¶
GroupShow authorizes one group: the admin family and product bearers see everything; a user bearer their own group (membership or ownership); a license bearer the license's group.
func GroupWrite ¶
GroupWrite authorizes create/update/destroy: admin, developer and product bearers.
func KeyIndexPostCheck ¶
KeyIndexPostCheck mirrors KeyPolicy#index?'s product post-check.
func KeyRelationship ¶
KeyRelationship mirrors Keys::{Product,Policy}Policy#show?: the admin family, or the product owning the key's policy.
func LicenseAction ¶
LicenseAction is the shared record clause of the acting routes (revoke, renew, check-in, check-out, validate, suspend, reinstate, usage): admin family / own product; revoke, renew and check-in additionally admit the owner of an unprotected license, check-out and validate also licensees and the license itself, usage.increment also the license bearer.
func LicenseCreate ¶
LicenseCreate mirrors LicensePolicy#create?.
func LicenseDestroy ¶
LicenseDestroy mirrors LicensePolicy#destroy?.
func LicenseEntitlementsAttach ¶
LicenseEntitlementsAttach mirrors Licenses::EntitlementPolicy#attach?/ detach?: admin, developer, sales agent or the owning product.
func LicenseGroupUpdate ¶
LicenseGroupUpdate mirrors Licenses::GroupPolicy#update?: admin, developer, sales agent or the owning product.
func LicenseIndexPostCheck ¶
LicenseIndexPostCheck mirrors LicensePolicy#index?: the admin family always; a product bearer only pages of its own; a user only pages she owns or is attached to (attached lists her licensee licenses); the license bearer only pages holding itself.
func LicenseOwnerUpdate ¶
LicenseOwnerUpdate mirrors Licenses::OwnerPolicy#update?: admin, developer, sales agent or the owning product.
func LicensePolicyUpdate ¶
LicensePolicyUpdate mirrors Licenses::PolicyPolicy#update?: admin, developer or sales agent; the owning product when the target policy is its own; the owner of an unprotected license to an unprotected policy.
func LicenseRelationshipShow ¶
LicenseRelationshipShow mirrors the index/show guards of the licenses sub-policies (machines, users, entitlements, group, owner, policy, product): the admin family, the owning product, the owner or an attached user, or the license itself.
func LicenseShow ¶
LicenseShow mirrors LicensePolicy#show?.
func LicenseTokenCreate ¶
LicenseTokenCreate mirrors Licenses::TokenPolicy#create?: admin, developer, sales agent or the owning product.
func LicenseTokenIndex ¶
LicenseTokenIndex mirrors Licenses::TokenPolicy#index?/show?: the admin family or the owning product (never a user or the license).
func LicenseUpdate ¶
LicenseUpdate mirrors LicensePolicy#update? (users and licenses cannot update at all).
func LicenseUsageWrite ¶
LicenseUsageWrite mirrors Licenses::UsagePolicy: increment admits the owner of an unprotected license and the license itself; decrement/reset only the admin family and the owning product.
func LicenseUsersAttach ¶
LicenseUsersAttach mirrors Licenses::UserPolicy#attach?/detach?: the admin family, the owning product, or the owner of an unprotected license.
func LicenseVisibleToUser ¶
LicenseVisibleToUser answers whether the user owns or is attached to the license (bearer.license_ids covers owner ∪ licensees).
func MachineCheckOut ¶ added in v0.0.5
MachineCheckOut mirrors MachinePolicy#check_out? (machine_policy.rb:98-114): the admin family; the product bearer its product's; a user machines she owns, of licenses she owns or is a user of, never a protected license; the license bearer its own. Read only is not admitted.
func MachineCreate ¶ added in v0.0.5
MachineCreate mirrors MachinePolicy#create? (machine_policy.rb:44-60): admin, developer and sales agent; the product bearer a license of its product; a user only as the machine's owner or on a license she owns, never a protected license; the license bearer only itself. licensed is false when the license does not exist (record.license is nil).
func MachineDestroy ¶ added in v0.0.5
MachineDestroy mirrors MachinePolicy#destroy? (machine_policy.rb:80-96): admin, developer and sales agent; the product bearer its product's; a user as the machine's owner or the license's owner, never a protected license; the license bearer always its own.
func MachineLicenseOwnerShow ¶ added in v0.0.5
MachineLicenseOwnerShow mirrors Machines::V1x5::UserPolicy#show?: the admin family; the product bearer its product's; a user only as the license's owner; the license bearer its own.
func MachinePing ¶ added in v0.0.5
MachinePing mirrors Machines::HeartbeatPolicy#ping? (machines/heartbeat_policy.rb:7-25): admin and developer only on the admin side; the product bearer its product's; a user as the machine's owner or the license's owner, never a protected license; the license bearer its own.
func MachineProof ¶ added in v0.0.5
MachineProof mirrors Machines::V1x0::ProofPolicy#create?: admin, developer and sales agent; the product bearer its product's; the license's owner, never a protected license; the license bearer its own.
func MachineRelationshipUpdate ¶ added in v0.0.5
MachineRelationshipUpdate mirrors Machines::OwnerPolicy#update? and Machines::GroupPolicy#update?: admin, developer and sales agent, or the product bearer of the machine's product.
func MachineResetHeartbeat ¶ added in v0.0.5
MachineResetHeartbeat mirrors Machines::HeartbeatPolicy#reset? (machines/heartbeat_policy.rb:27-41): admin, developer and sales agent, or the product bearer of the machine's product. No user, no license.
func MachineShow ¶ added in v0.0.5
MachineShow mirrors MachinePolicy#show? (machine_policy.rb:24-42): the admin family; the product bearer its product's; a user the machines of its licenses; the license bearer its own.
func MachineUpdate ¶ added in v0.0.5
MachineUpdate mirrors MachinePolicy#update? (machine_policy.rb:62-78): admin, developer, sales agent and support agent (never read only); the product bearer its product's; a user as the machine's owner or the license's owner, never a protected license; the license bearer only itself and never a protected license.
func MachineUsageRead ¶ added in v0.0.5
MachineUsageRead guards the usage journal read (a backplane extension): the vendor side only — the admin family and the machine's product.
func MachineVendorMetadata ¶ added in v0.0.14
MachineVendorMetadata guards the vendor keys of a machine's metadata (create: before is nil): the staff writers and the machine's product change them freely; anyone else must leave every one as it was. Only an activation needs it: an update's metadata is the vendor's alone already.
func PolicyEntitlementsWrite ¶
PolicyEntitlementsWrite mirrors Policies::EntitlementPolicy#attach?/ detach?: admin, developer, sales agent, or the owning product.
func PolicyIndexPostCheck ¶
func PolicyIndexPostCheck(p Principal, page []domain.Policy, userPolicies map[uuid.UUID]struct{}, licensePolicyID uuid.UUID) error
PolicyIndexPostCheck mirrors PolicyPolicy#index?'s post-pagination checks over the loaded page: the admin family always; a product bearer only pages of its own policies; a license only pages holding just its own policy; a user only pages of her policies.
func PolicyPoolPop ¶
PolicyPoolPop mirrors Policies::PoolPolicy#pop?.
func PolicyPoolPostCheck ¶
PolicyPoolPostCheck mirrors PoolPolicy#index?'s checks: the admin family always; a product bearer only pages of its own keys.
func PolicyRelationship ¶
PolicyRelationship mirrors the policies/*_policy.rb index/show guards over a policy's sub-resources (product, licenses, pool, entitlements): the admin family, or the product owning the policy.
func PolicyShow ¶
PolicyShow mirrors PolicyPolicy#show?: the admin family always; the product bearer its own; a user hers; a license its own.
func PolicyWrite ¶
PolicyWrite mirrors PolicyPolicy#create?/update?/destroy? (sales agents may create and update but not destroy).
func ProductIndex ¶
ProductIndex mirrors ProductPolicy#index?: the admin family always; user and license bearers pass only their licensed/open post-checks (the scoped queries already narrow theirs). The product bearer has no index clause at all — it is denied even its own row.
func ProductMayRead ¶
ProductMayRead answers whether the product-scoped endpoint's product is authorized to read the event's resource (BroadcastWebhookService's ActionPolicy check, per resource type): products see their own product, policy, key and product-token events, the events of plain users (UserPolicy#show? allows any product for user-role records), and the account-global entitlement and group events; user-scoped second factors are never sent to product endpoints. The cases that need a lookup (user tokens of licensed users, policy entitlement joins) are resolved by the publisher before this check.
func ProductRelationship ¶
ProductRelationship mirrors the products/*_policy.rb index/show guards (policies, licenses, machines, users): the admin family, or the product itself.
func ProductShow ¶
ProductShow mirrors ProductPolicy#show?: the admin family always; the product bearer itself; a user the product when open or her own licensed one; a license the product when open or its own.
func ProductTokenCreate ¶
ProductTokenCreate mirrors Products::TokenPolicy#create?: the admin family's writers only.
func ProductTokenIndex ¶
ProductTokenIndex mirrors Products::TokenPolicy#index?: the admin family, and — the reference's quirk — the product bearer for its own product.
func ProductTokenShow ¶
ProductTokenShow mirrors Products::TokenPolicy#show?: the admin family, or the product bearer reading its own token.
func ProductWrite ¶
ProductWrite mirrors ProductPolicy#create?/update?/destroy? (the update admits the product bearer itself).
func ReasonLacksPermission ¶
ReasonLacksPermission is the verify_permissions! reason when the bearer's role itself does not hold the permission.
func Require ¶
Require authorizes the permission for the context's principal. The returned error is the 403 document with the reference's reason: the bearer's role lacking the permission ("<role> lacks permission to perform action"), or — for token authentication whose restrictions removed it — "token lacks permission to perform action".
func RequireBearerKind ¶
RequireBearerKind authorizes the bearer kinds (any of kinds).
func RolePermissions ¶
RolePermissions returns the role's CE default permission set.
func SecondFactorShow ¶
SecondFactorShow authorizes reading the user's second factors: an admin sees everyone's; the other admin-family roles, products and plain users only their own.
func SecondFactorWrite ¶
SecondFactorWrite authorizes create/update/destroy: like Show, but read-only bearers are always denied.
func SubresourceCreate ¶ added in v0.0.5
SubresourceCreate mirrors create?: admin, developer and sales agent; the product bearer its product's; the machine's or license's owner, never on a protected license; the license bearer its own.
func SubresourceDestroy ¶ added in v0.0.5
SubresourceDestroy mirrors destroy?: create?'s table.
func SubresourceUpdate ¶ added in v0.0.5
SubresourceUpdate mirrors update?: create?'s table plus support agents.
func TokenGenerateForUser ¶
TokenGenerateForUser authorizes minting a token for the target user (the /users/{id}/tokens route): admin/developer for self or a plain user, product for a plain user licensed to it; other bearers are denied.
func TokenRegenerate ¶
func TokenRegenerate(p Principal, token domain.Token, userOfProduct, licenseOfProduct func() bool) error
TokenRegenerate authorizes regeneration: admin and developer for any bearer; a product bearer its users'/licenses' tokens; everyone else their own.
func TokenRevoke ¶
func TokenRevoke(p Principal, token domain.Token, userOfProduct, licenseOfProduct func() bool) error
TokenRevoke authorizes revocation: admin, developer for any bearer; a product bearer its users'/licenses' tokens; everyone else their own.
func TokenScopeKind ¶
TokenScopeKind selects the index scope of the tokens relation for the principal ("" = every record).
func TokenShow ¶
TokenShow authorizes one token: the admin family sees everything; a product bearer its users' and its licenses' tokens; everyone else only their own.
func UserCreate ¶
UserCreate authorizes creating the record (privilege escalation included).
func UserDestroy ¶
UserDestroy authorizes deleting the record.
func UserPasswordUpdate ¶
UserPasswordUpdate authorizes the update-password action: only the bearer themself.
func UserScopeKind ¶
UserScopeKind selects the index scope of the users relation for the principal ("" = every record).
func UserShow ¶
UserShow authorizes one record: admin-family sees everything; a product bearer plain-user records; a user bearer self and teammates; a license bearer its owner and attached users. The user.read permission check runs in the scenario before this.
func UserUpdate ¶
UserUpdate authorizes mutating the record.
func WebhookEndpointIndex ¶
func WebhookEndpointIndex(p Principal, page []domain.WebhookEndpoint) error
WebhookEndpointIndex mirrors WebhookEndpointPolicy#index?: the admin family; the product bearer passes only a page of its own endpoints (the scoped query already narrowed it — the post-check reasserts).
func WebhookEndpointShow ¶
func WebhookEndpointShow(p Principal, endpoint domain.WebhookEndpoint) error
WebhookEndpointShow mirrors WebhookEndpointPolicy#show?: the admin read roles (admin, developer, read_only; not sales or support), or the product bearer for its own endpoint.
func WebhookEndpointWrite ¶
func WebhookEndpointWrite(p Principal, endpoint domain.WebhookEndpoint) error
WebhookEndpointWrite mirrors WebhookEndpointPolicy#create?/update?/ destroy?: the write family (admin, developer), or the product bearer for its own endpoint (create infers the bearer's product).
func WebhookEventIndex ¶
func WebhookEventIndex(p Principal, page []domain.WebhookEvent, productOf func(uuid.UUID) uuid.UUID) error
WebhookEventIndex mirrors WebhookEventPolicy#index?: the admin family, or the product bearer for events of its own endpoints.
func WebhookEventManage ¶
WebhookEventManage mirrors WebhookEventPolicy#destroy?/retry?: the write family only (products included are denied).
func WebhookEventShow ¶
func WebhookEventShow(p Principal, _ domain.WebhookEvent, productID uuid.UUID, hasEndpoint bool) error
WebhookEventShow mirrors WebhookEventPolicy#show?.
Types ¶
type Principal ¶
type Principal struct {
// Console is set only by the in-process operator bridge, never from a
// credential. Its synthetic bearer is not a persisted user.
Console bool
// UserBanned is the live password-authenticated user state for TokenPolicy.
UserBanned bool
// BearerType is the wire type: users, products or licenses.
BearerType string
BearerID uuid.UUID
Role domain.Role
// TokenID is zero for password (and license-key) authentication.
TokenID uuid.UUID
// Permissions is the effective set (role defaults, or the token
// intersection for token authentication).
Permissions map[string]struct{}
// License carries the authenticated license for license-key auth.
License *domain.LicenseAuth
}
Principal is the authenticated caller: what every scenario authorizes against.
func PrincipalOf ¶
PrincipalOf loads the principal from the context; the zero value when the request is anonymous.
func System ¶ added in v0.0.18
func System() Principal
System is the in-process principal of the declared catalog's reconcile: an admin no credential, header or console call produces.
func (Principal) BearerHeader ¶
BearerHeader answers the Keygen-Bearer response header value.