Role-Based Access Control and Feature Gating: TCTF's Permission System

01Two Layers: Permission and Quota

Most platforms have one access control layer — either RBAC or subscription tiers. TCTF has both, and they serve different purposes.

RBAC answers the question: can this user do this? It is binary — yes or no. An admin can reset another user's MFA. A member cannot. A moderator can review flagged content. A support staff member can view user profiles but cannot delete them. RBAC is about capability.

The feature matrix answers the question: how much can this user do? It is quantitative — a number, a limit, a quota. A free user can create 5 projects. A pro user can create 25. A premium user can create 100. An enterprise user has no limit. The feature matrix is about capacity.

Both layers are checked on every request. First, the Cognito middleware checks RBAC — does the user's role grant the required permission? If not, the request is denied with a 403. Then, the feature matrix checks the quota — has the user exceeded their tier's limit for this action? If so, the request is denied with a 429 and an upgrade prompt.

This two-layer model means a member with a premium subscription can create 100 projects (feature matrix allows it) but cannot manage other users (RBAC denies it). An admin with a free subscription can manage users (RBAC allows it) but is still subject to storage limits (feature matrix enforces it). The layers are independent and complementary.

🔐

RBAC: CAN the user do this? (permission) Feature Matrix: HOW MUCH can they do? (quota) Both checked on every request. Independent and complementary.

02The Role Hierarchy

TCTF defines six roles, organized in a hierarchy from most privileged to least.

ADMIN has all permissions — represented by the wildcard '*'. Admins can do anything on the platform. This role is reserved for the core team.

STAFF_MANAGER has all staff permissions plus management capabilities — MFA admin (reset other users' MFA), password admin, user MFA management, and audit log access. This is for team leads who manage other staff members.

STAFF has the core operational permissions — user moderation, content moderation, report access, profile management, and their own MFA and password management. This is the standard staff role.

STAFF_SUPPORT has a focused subset — MFA status checks, password resets, user profile viewing. This is for support agents who help users with account issues but do not need full moderation capabilities.

STAFF_BASIC has the minimum staff permissions — MFA status viewing, password management, and profile updates. This is for staff members who need platform access but not operational tools.

MEMBER is the default role for registered users. Members can read and update their own profile, create projects, join teams, manage their own MFA and password. They cannot access other users' data, moderate content, or view reports.

03Permissions: Granular and Composable

Permissions are strings that follow a resource:action pattern. profile:read, users:write, content:moderate, mfa:admin, password:reset. Each permission grants access to a specific capability.

The permission set is organized by domain: profile permissions (read, write, update), user management (read, write, delete, moderate, mfa:manage, password:reset), content management (read, write, moderate), project management (create, manage), team management (join, manage), MFA (setup, verify, status, disable, admin, settings:read, settings:update, settings:admin), password (reset, change, validate, admin), and system (reports:read, audit:read, system:admin).

Permissions are composable. A role is defined as an array of permission strings. The STAFF role includes users:read, users:moderate, content:moderate, reports:read, and all MFA and password self-management permissions. The STAFF_MANAGER role includes everything in STAFF plus mfa:admin, users:mfa:manage, password:admin, and audit:read.

The hasPermission function checks access: it takes the user's role, their explicit permissions, and the required permission. Admins always pass (wildcard). For other roles, it checks the role's permission array first, then falls back to explicit user permissions. This means a user can have permissions beyond their role — useful for temporary elevated access without changing the role.

🔧

Permissions follow resource:action pattern. Roles are arrays of permissions. hasPermission checks role first, then explicit permissions. Admins always pass via wildcard.

04The Feature Matrix: Plans × Tiers

The feature matrix is a two-dimensional grid: membership plans on one axis, subscription tiers on the other.

Membership plans define the type of account: Individual (single user), Team (small group), Organization (company or large team). Each plan has different base capabilities — an organization can have more team members than an individual.

Subscription tiers define the level within a plan: Free, Pro, Premium, Enterprise. Each tier increases the limits — more projects, more storage, more API calls, more AI translation credits.

The combination of plan and tier determines the exact limits. An Individual Free user gets 5 projects and 1GB storage. A Team Pro user gets 25 projects and 10GB storage. An Organization Enterprise user gets unlimited everything.

The feature matrix is defined as a constant in tctf-utils. Every plan-tier combination maps to a PlanTierConfig that includes FeatureLimits (numeric quotas) and FeatureAccess (boolean feature flags). The getPlanTierConfig, getFeatureLimits, and getFeatureAccess functions look up the configuration for any plan-tier combination.

05Feature Limits and Access Flags

FeatureLimits defines the numeric quotas: maximum projects, maximum team members, storage in bytes, API rate limit per minute, AI translation credits per day, and more. The isUnlimited helper checks if a limit is set to the maximum safe integer — the convention for unlimited access.

FeatureAccess defines the boolean flags: can this user access advanced analytics? Can they use AI translation? Can they create private projects? Can they use custom branding? These are features that are either available or not — no numeric limit, just on or off.

The analytics level is a special case — it is an enum (basic, standard, advanced, custom) rather than a boolean. Free users get basic analytics (page views, simple counts). Pro users get standard (trends, comparisons). Premium users get advanced (cohort analysis, funnels). Enterprise users get custom (configurable dashboards, data export).

When a user tries to create their 6th project on a Free plan, the feature matrix check returns the limit (5), the current count (5), and the upgrade options — which plan-tier combinations would allow more projects. The frontend uses this to show a contextual upgrade prompt: 'You have reached your project limit. Upgrade to Pro for 25 projects.'

📊

Feature limits are numeric (projects: 5/25/100/∞). Feature access is boolean (AI translation: on/off). Analytics level is tiered (basic/standard/advanced/custom). Upgrade prompts are contextual.

06Tier-Based Rate Limiting

The feature matrix integrates with the rate limiting service covered in Framework Series #4. The UserTierManager assigns and tracks user tiers, and the TierBasedRateLimitService enforces different rate limits per tier.

A free user might be limited to 100 API requests per minute. A premium user gets 2000. An enterprise user gets unlimited. The tier is extracted from the JWT token (subscription_tier claim), the API key prefix (ent_ for enterprise), or the X-User-Tier header.

Tier upgrades and downgrades are handled atomically. When a user upgrades from Free to Pro, the UserTierManager updates their tier in the cache, and the next rate limit check uses the new limits. When a subscription expires, the tier is automatically downgraded to Free.

The tier-based rate limiting also supports geographic rules — a premium user in a high-risk region might still get stricter limits than a premium user in a low-risk region. The tier provides the base limit, and geographic rules adjust it.

07How It All Works Together

Here is the complete access control flow for a single API request.

The request arrives at API Gateway. The Cognito authorizer validates the JWT. The Lambda handler starts. The withErrorHandling wrapper generates a correlation ID. The Cognito middleware extracts the user context — userId, groups, permissions.

Layer 1 (RBAC): The middleware calls requirePermissions with the required permission for this endpoint. The hasPermission function checks the user's role against the required permission. If denied, a 403 AuthorizationError is thrown and the error handler returns a formatted response.

Layer 2 (Feature Matrix): The handler calls getFeatureLimits with the user's plan and tier. It checks the current count against the limit. If exceeded, a 429 response is returned with upgrade options.

Layer 3 (Rate Limiting): The rate limit middleware checks the user's request count against their tier's rate limit. If exceeded, a 429 response is returned with a Retry-After header.

All three layers are shared utilities in tctf-utils. Every service uses the same RBAC model, the same feature matrix, and the same rate limiting. A permission change, a tier adjustment, or a rate limit update applies across all 34 services immediately — no per-service configuration, no inconsistencies.

✅

Three layers on every request: RBAC (can they?), Feature Matrix (how much?), Rate Limiting (how fast?). All shared in tctf-utils. One change applies across 34 services.