Documentation
¶
Overview ¶
Role claim extraction from OIDC tokens.
Auth0 delivers kombify platform roles via a namespaced custom claim set by a Post-Login Action:
"https://kombify.io/roles": ["global_admin"]
Auth0 also surfaces flat "role" (string) and "roles" ([]string) claims in some legacy flows. This file provides extractors that understand both shapes and always return canonical kombify platform roles in descending privilege order.
TypeScript counterpart:
@kombify/contracts — kombify-Core/packages/contracts/src/role-claims.ts
Package role defines the canonical role and plan types for the kombify platform.
Roles control authorization (what a user may do). Plans control entitlements (what features a user may access).
Self-hosted tools (Stack, Sim, StackKits) may define their own local roles (e.g. viewer/user/admin). Platform roles only apply in SaaS context via Auth0; delivered to origins via the Cloudflare edge signed X-User-Roles header.
Canonical SSOT: kombify-Core/standards/PLATFORM-CONSOLIDATION-PLAN.md §K1.
Index ¶
Constants ¶
const DefaultRoleClaimNamespace = "https://kombify.io/roles"
DefaultRoleClaimNamespace is the canonical Auth0 custom-claim namespace for kombify platform roles. Set by the "kombify Role Claim" Post-Login Action.
Variables ¶
AllPlans lists the canonical plans in ascending tier order. Aliases (ProPlus, AllYouNeed, Business) are intentionally excluded.
var AllRoles = []Role{GlobalAdmin, Admin, Developer, Manager, User}
AllRoles lists every defined role in descending privilege order.
var StaffRoles = []Role{GlobalAdmin, Admin, Developer, Manager}
StaffRoles lists roles that grant access to Admin Center and Company Tools.
Functions ¶
This section is empty.
Types ¶
type Plan ¶
type Plan string
Plan represents a subscription plan (entitlement tier). Canonical enum per kombify-Core/standards/ENTITLEMENTS-ARCHITECTURE.md §3 / BILLING-ENTITLEMENT-STANDARD.md: anonymous, free, starter, pro, ayn. Mirrors the Cloudflare edge normalizer (kombify-Gateway/cloudflare-edge/src/entitlements.ts).
const ( // Anonymous is the pseudo-tier for unauthenticated access. It ranks // below Free and shares the lowest level with unknown plans. Anonymous Plan = "anonymous" Free Plan = "free" Starter Plan = "starter" Pro Plan = "pro" ProPlus Plan = "pro_plus" // Alias for Pro; accepted in IsValid/Level/ParsePlan. // Ayn is the canonical identifier for the "All You Need" plan tier. // Use Ayn in all new code. AllYouNeed and Business are backward-compat // aliases for persisted JWT/DB values — all three resolve to the same // level (kombify-Gateway ADR 0002: there is no separate business tier). Ayn Plan = "ayn" AllYouNeed Plan = "all_you_need" // Alias for Ayn; accepted in IsValid/Level/ParsePlan. Business Plan = "business" // Alias for Ayn; accepted in IsValid/Level/ParsePlan. )
func NormalizePlan ¶
NormalizePlan is ParsePlan with the edge default: unknown values normalize to Free (the floor for an authenticated principal; unauthenticated traffic never reaches origins with a tier header).
func ParsePlan ¶
ParsePlan normalizes a raw tier string (JWT claim, X-User-Tier header, DB value) to its canonical plan. Matching is case-insensitive and treats '-' as '_'. ok is false for unknown values.
type Role ¶
type Role string
Role represents a platform-level authorization role. Stored in Auth0 project roles and propagated via the Cloudflare edge signed X-User-* header envelope (go-common/edgeauth).
const ( // GlobalAdmin is the single platform owner with unrestricted access. GlobalAdmin Role = "global_admin" // Admin is a Kombiverse Labs administrator; below GlobalAdmin, above Developer. // Added in canonical set 2026-06-05; previously defined only in Administration/Cloud/Desk locally. Admin Role = "admin" // Developer has near-admin access to Admin Center, Company Tools, and all kombify tools. Developer Role = "developer" // Manager is a Kombiverse Labs employee with access to Admin Center, Company Tools, and all kombify tools. Manager Role = "manager" // User is a standard end customer (B2C or B2B). Default role for all customers. User Role = "user" )
func ExtractAllRolesFromClaims ¶
ExtractAllRolesFromClaims returns every known kombify role present in the claim set, sorted in descending privilege order (highest first). Duplicate and unknown entries are removed. If no valid role is found, the result is User so callers always get a safe default.
func ExtractRoleFromClaims ¶
ExtractRoleFromClaims returns the highest-priority known role from a decoded OIDC claim set. It inspects, in order:
- The namespaced claim (default "https://kombify.io/roles"), expected to be a []string (Auth0 Post-Login Action shape).
- A flat "roles" claim ([]string or []any of strings) for legacy / Kong header forwards.
- A flat "role" claim (string) for single-role legacy tokens.
Unknown role strings are ignored. If no valid kombify role is found, the default User role is returned so downstream code can rely on a non-empty value.
func (Role) IsStaff ¶
IsStaff returns true if this role is a staff role (any role in StaffRoles: global_admin, admin, developer, manager).
Source Files