access

package
v0.0.18 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 8 Imported by: 0

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

View Source
const (
	BearerUser    = "users"
	BearerProduct = "products"
	BearerLicense = "licenses"
)

Bearer kinds (the wire resource types of the bearers).

View Source
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.

View Source
const ReasonMustHaveUserRole = " (must have a user role)"

ReasonMustHaveUserRole is the ban/unban deny reason.

View Source
const ReasonNoCredential = " (ensure a token or license is present and valid)"

ReasonNoCredential is the policy-deny reason of an anonymous bearer.

View Source
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.

View Source
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

View Source
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

func Effective(role domain.Role, tokenPermissions []string) map[string]struct{}

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

func EntitlementShow(p Principal, id uuid.UUID, entitlements map[uuid.UUID]struct{}) error

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

func EntitlementWrite(p Principal) error

EntitlementWrite mirrors EntitlementPolicy#create?/update?/destroy?.

func GroupLicenseShow

func GroupLicenseShow(p Principal, license domain.License, groupOwned bool) error

GroupLicenseShow is Groups::LicensePolicy#show?: unlike an ordinary license show, this route admits group owners without individual ownership.

func GroupOwnersRead

func GroupOwnersRead(p Principal, group domain.Group, memberOrOwner func(domain.Group) bool) error

GroupOwnersRead authorizes the owners index/show like GroupShow (membership or ownership qualifies a user bearer).

func GroupOwnersWrite

func GroupOwnersWrite(p Principal) error

GroupOwnersWrite authorizes attach/detach: admin, developer, product.

func GroupShow

func GroupShow(p Principal, group domain.Group, memberOrOwner func(domain.Group) bool) error

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

func GroupWrite(p Principal) error

GroupWrite authorizes create/update/destroy: admin, developer and product bearers.

func KeyIndexPostCheck

func KeyIndexPostCheck(p Principal, page []domain.Key) error

KeyIndexPostCheck mirrors KeyPolicy#index?'s product post-check.

func KeyRelationship

func KeyRelationship(p Principal, key domain.Key) error

KeyRelationship mirrors Keys::{Product,Policy}Policy#show?: the admin family, or the product owning the key's policy.

func KeyShow

func KeyShow(p Principal, key domain.Key) error

KeyShow mirrors KeyPolicy#show?.

func KeyWrite

func KeyWrite(p Principal, key domain.Key) error

KeyWrite mirrors KeyPolicy#create?/update?/destroy?.

func LicenseAction

func LicenseAction(p Principal, license domain.License, clause string, userAttached bool) error

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

func LicenseCreate(p Principal, license domain.License) error

LicenseCreate mirrors LicensePolicy#create?.

func LicenseDestroy

func LicenseDestroy(p Principal, license domain.License) error

LicenseDestroy mirrors LicensePolicy#destroy?.

func LicenseEntitlementsAttach

func LicenseEntitlementsAttach(p Principal, license domain.License) error

LicenseEntitlementsAttach mirrors Licenses::EntitlementPolicy#attach?/ detach?: admin, developer, sales agent or the owning product.

func LicenseGroupUpdate

func LicenseGroupUpdate(p Principal, license domain.License) error

LicenseGroupUpdate mirrors Licenses::GroupPolicy#update?: admin, developer, sales agent or the owning product.

func LicenseIndexPostCheck

func LicenseIndexPostCheck(p Principal, page []domain.License, attached map[uuid.UUID]bool) error

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

func LicenseOwnerUpdate(p Principal, license domain.License) error

LicenseOwnerUpdate mirrors Licenses::OwnerPolicy#update?: admin, developer, sales agent or the owning product.

func LicensePolicyUpdate

func LicensePolicyUpdate(p Principal, license domain.License, target domain.Policy) error

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

func LicenseRelationshipShow(p Principal, license domain.License, userAttached bool) error

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

func LicenseShow(p Principal, license domain.License, userAttached bool) error

LicenseShow mirrors LicensePolicy#show?.

func LicenseTokenCreate

func LicenseTokenCreate(p Principal, license domain.License) error

LicenseTokenCreate mirrors Licenses::TokenPolicy#create?: admin, developer, sales agent or the owning product.

func LicenseTokenIndex

func LicenseTokenIndex(p Principal, license domain.License) error

LicenseTokenIndex mirrors Licenses::TokenPolicy#index?/show?: the admin family or the owning product (never a user or the license).

func LicenseUpdate

func LicenseUpdate(p Principal, license domain.License) error

LicenseUpdate mirrors LicensePolicy#update? (users and licenses cannot update at all).

func LicenseUsageWrite

func LicenseUsageWrite(p Principal, license domain.License, action string) error

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

func LicenseUsersAttach(p Principal, license domain.License) error

LicenseUsersAttach mirrors Licenses::UserPolicy#attach?/detach?: the admin family, the owning product, or the owner of an unprotected license.

func LicenseVisibleToUser

func LicenseVisibleToUser(p Principal, license domain.License, userAttached bool) bool

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

func MachineCheckOut(p Principal, m domain.Machine) error

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

func MachineCreate(p Principal, license domain.License, licensed bool, owner uuid.NullUUID) error

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

func MachineDestroy(p Principal, m domain.Machine) error

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

func MachineLicenseOwnerShow(p Principal, m domain.Machine) error

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

func MachinePing(p Principal, m domain.Machine) error

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

func MachineProof(p Principal, m domain.Machine) error

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

func MachineRelationshipUpdate(p Principal, m domain.Machine) error

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

func MachineResetHeartbeat(p Principal, m domain.Machine) error

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

func MachineShow(p Principal, m domain.Machine) error

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

func MachineUpdate(p Principal, m domain.Machine) error

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

func MachineUsageRead(p Principal, m domain.Machine) error

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

func MachineVendorMetadata(p Principal, m domain.Machine, before, after map[string]any) error

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

func PolicyEntitlementsWrite(p Principal, policy domain.Policy) error

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

func PolicyPoolPop(p Principal, policy domain.Policy) error

PolicyPoolPop mirrors Policies::PoolPolicy#pop?.

func PolicyPoolPostCheck

func PolicyPoolPostCheck(p Principal, policy domain.Policy, page []domain.Key) error

PolicyPoolPostCheck mirrors PoolPolicy#index?'s checks: the admin family always; a product bearer only pages of its own keys.

func PolicyRelationship

func PolicyRelationship(p Principal, policy domain.Policy) error

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

func PolicyShow(p Principal, policy domain.Policy, ownedByUser, ownedByLicense bool) error

PolicyShow mirrors PolicyPolicy#show?: the admin family always; the product bearer its own; a user hers; a license its own.

func PolicyWrite

func PolicyWrite(p Principal, policy domain.Policy, destroy bool) error

PolicyWrite mirrors PolicyPolicy#create?/update?/destroy? (sales agents may create and update but not destroy).

func ProductIndex

func ProductIndex(p Principal, allOpenOrLicensed bool) error

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

func ProductMayRead(productID uuid.UUID, resource any) bool

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

func ProductRelationship(p Principal, product domain.Product) error

ProductRelationship mirrors the products/*_policy.rb index/show guards (policies, licenses, machines, users): the admin family, or the product itself.

func ProductShow

func ProductShow(p Principal, product domain.Product, licensedToBearer bool) error

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

func ProductTokenCreate(p Principal) error

ProductTokenCreate mirrors Products::TokenPolicy#create?: the admin family's writers only.

func ProductTokenIndex

func ProductTokenIndex(p Principal, product domain.Product) error

ProductTokenIndex mirrors Products::TokenPolicy#index?: the admin family, and — the reference's quirk — the product bearer for its own product.

func ProductTokenShow

func ProductTokenShow(p Principal, product domain.Product, tokenBearerID uuid.UUID) error

ProductTokenShow mirrors Products::TokenPolicy#show?: the admin family, or the product bearer reading its own token.

func ProductWrite

func ProductWrite(p Principal, product domain.Product) error

ProductWrite mirrors ProductPolicy#create?/update?/destroy? (the update admits the product bearer itself).

func ReasonLacksPermission

func ReasonLacksPermission(role domain.Role) string

ReasonLacksPermission is the verify_permissions! reason when the bearer's role itself does not hold the permission.

func Require

func Require(ctx context.Context, permission string) error

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

func RequireBearerKind(ctx context.Context, kinds ...string) error

RequireBearerKind authorizes the bearer kinds (any of kinds).

func RolePermissions

func RolePermissions(role domain.Role) map[string]struct{}

RolePermissions returns the role's CE default permission set.

func RoleRank

func RoleRank(r domain.Role) int

RoleRank is the privilege order of the roles (Role#<=>).

func SecondFactorShow

func SecondFactorShow(p Principal, userID uuid.UUID) error

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

func SecondFactorWrite(p Principal, userID uuid.UUID) error

SecondFactorWrite authorizes create/update/destroy: like Show, but read-only bearers are always denied.

func SubresourceCreate added in v0.0.5

func SubresourceCreate(p Principal, m domain.Machine) error

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

func SubresourceDestroy(p Principal, m domain.Machine) error

SubresourceDestroy mirrors destroy?: create?'s table.

func SubresourceUpdate added in v0.0.5

func SubresourceUpdate(p Principal, m domain.Machine) error

SubresourceUpdate mirrors update?: create?'s table plus support agents.

func TokenGenerateForUser

func TokenGenerateForUser(p Principal, user domain.User, licensedTo func() bool) error

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

func TokenScopeKind(p Principal) string

TokenScopeKind selects the index scope of the tokens relation for the principal ("" = every record).

func TokenShow

func TokenShow(p Principal, token domain.Token, userOfProduct, licenseOfProduct func() bool) error

TokenShow authorizes one token: the admin family sees everything; a product bearer its users' and its licenses' tokens; everyone else only their own.

func UserBan

func UserBan(p Principal, user domain.User) error

UserBan authorizes ban/unban: only plain-user targets are bannable.

func UserCreate

func UserCreate(p Principal, accountProtected bool, role domain.Role) error

UserCreate authorizes creating the record (privilege escalation included).

func UserDestroy

func UserDestroy(p Principal, user domain.User) error

UserDestroy authorizes deleting the record.

func UserPasswordUpdate

func UserPasswordUpdate(p Principal, user domain.User) error

UserPasswordUpdate authorizes the update-password action: only the bearer themself.

func UserScopeKind

func UserScopeKind(p Principal) string

UserScopeKind selects the index scope of the users relation for the principal ("" = every record).

func UserShow

func UserShow(p Principal, user domain.User, teammate, licenseUser func() bool) error

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

func UserUpdate(p Principal, user domain.User, role domain.Role) error

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

func WebhookEventManage(p Principal) error

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?.

func Whatami

func Whatami(p Principal) string

Whatami names the bearer like the reference's policy whatami (the humanized role: user, admin, developer, read only, sales agent, support agent, product, license).

func With

With stores the principal in the context.

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

func PrincipalOf(ctx context.Context) Principal

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) Allows

func (p Principal) Allows(permission string) bool

Allows reports whether the principal holds the permission.

func (Principal) BearerHeader

func (p Principal) BearerHeader() string

BearerHeader answers the Keygen-Bearer response header value.

func (Principal) IsLicense

func (p Principal) IsLicense() bool

func (Principal) IsProduct

func (p Principal) IsProduct() bool

func (Principal) IsTokenAuthn

func (p Principal) IsTokenAuthn() bool

func (Principal) IsUser

func (p Principal) IsUser() bool

IsUser/IsProduct/IsLicense are the bearer-kind checks.

Jump to

Keyboard shortcuts

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