Authentication, Onboarding & RBAC Flow Diagrams

1. System Overview

High-level view of user authentication, authorization, and feature access in Agencio Predict.

Key Security Principles

2. Login Flow (UI → Backend)

Complete login sequence from user input to authenticated session.

Login Response Structure

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user | editor | administrator | super_admin",
    "status": "active | pending_verification | pending_mfa | pending_subscription",
    "mfaRequired": true | false
  },
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "...",
  "expiresIn": 604800,
  "provider": "cognito | agencio | local",
  "nextStep": "verify-email | await-approval | enroll-mfa | subscribe | null",
  "sessionsRevoked": 2  // if session limit exceeded
}

File References

3. MFA Challenge Flow

Second-factor authentication for SMS and TOTP (authenticator apps).

MFA Challenge Types

TOTP Configuration

4. Session Management

Multi-device session tracking with configurable limits and timeout handling.

Session Data Structure

interface UserSession {
  id: string;
  userId: string;
  deviceName: string;      // "Chrome on Windows", "Safari on iOS"
  deviceType: 'desktop' | 'mobile' | 'tablet' | 'terminal' | 'unknown';
  ipAddress: string;
  locationCity: string;
  locationCountry: string;
  createdAt: Date;
  lastActivityAt: Date;
  expiresAt: Date;
  isCurrent: boolean;      // Highlighted in UI
}

Session Timeout Configuration

Revocation Reasons

5. Registration & Email Verification

New user signup flow with CAPTCHA, email verification, and optional admin approval.

Registration Gates

6. Onboarding Status Ladder

User status progression from registration to fully active account.

Status Routing

Onboarding Pages

7. Getting Started Hub

Centralized onboarding page with guided setup for 6 key features.

Setup Cards

API Endpoints

8. Feature Wizards

Step-by-step guided flows for complex feature setup.

Algorithm Builder Gates

Wizard Progress Storage

// localStorage key: agencio-algorithm-wizard-progress
{
  "version": 1,
  "currentStep": "backtest",
  "algorithmId": "uuid",
  "createdAt": "2026-05-19T10:00:00Z",
  "expiresAt": "2026-05-20T10:00:00Z",  // 24-hour expiry
  "data": {
    "backtestResults": {...},
    "validationResults": {...}
  }
}

9. Mini-Tours & Platform Tour

Contextual feature guides and full platform walkthrough.

Tour State Management

Tour API Endpoints

10. User Roles & Hierarchy

8 user roles with hierarchical inheritance.

Role Definitions

Role Inheritance

ROLE_HIERARCHY = {
  super_admin: [admin, administrator, editor, user, console_user, viewer],
  admin: [administrator, editor, user, console_user, viewer],
  administrator: [admin, editor, user, console_user, viewer],
  editor: [user, viewer],
  user: [viewer],
  console_user: [viewer],
  viewer: [],
  service: []
}

11. RBAC Permission System

Fine-grained permission checks for API endpoints.

Role → Permission Matrix

RBAC Functions

// Check if user has any of the specified roles (direct or inherited)
hasRole(user, ...roles: Role[]): boolean

// Check if user has all specified permissions
hasPermission(user, ...permissions: Permission[]): boolean

// Check if user has any of the specified permissions
hasAnyPermission(user, ...permissions: Permission[]): boolean

// Throw 403 if permission check fails
requirePermissions(user, ...permissions: Permission[]): void

// Throw 403 if role check fails
requireRoles(user, ...roles: Role[]): void

// Get all effective permissions for a user
getEffectivePermissions(user): Permission[]

12. Admin Route Protection

Admin panel access control and super_admin-only features.

Backend Admin Pattern

// In route.ts (thin wrapper)
export async function GET(request: NextRequest) {
  const adminError = await requireAdmin(request);
  if (adminError) return adminError;
  return handleListUsers(request);
}

// In handlers.ts
async function requireAdmin(request: NextRequest) {
  const user = await requireAuth(request);
  if (!isAdminRole(user.role)) {
    throw Errors.forbidden('Admin role required');
  }
  return user;
}

async function requireSuperAdmin(request: NextRequest) {
  const user = await requireAuth(request);
  if (!isSuperAdmin(user.role)) {
    throw Errors.forbidden('Super admin role required');
  }
  return user;
}

Org-Scoped Admin Access

13. License & Deployment Guard

Anti-piracy protection with License Server validation.

Machine Fingerprint

interface DeploymentFingerprint {
  deploymentId: string;      // From DEPLOYMENT_ID env
  machineHash: string;       // SHA256 of hardware info
  version: string;           // From APP_VERSION env
  environment: string;       // From NODE_ENV
  timestamp: number;         // Current epoch
}

// Machine hash computed from:
// - os.hostname()
// - os.platform()
// - os.arch()
// - os.cpus()[0].model
// - os.totalmem()
// - MAC addresses (sorted)

Response Signing

Environment Variables

14. Subscription & Billing Gates

Three-tier subscription model with feature gating.

Feature Access Check

// Non-throwing check
const result = await checkFeatureAccess(userId, 'trade_export_pdf');
// Returns: { allowed: boolean, planName, feature, upgradeRequired?, message? }

// Throwing check
await requireFeature(userId, 'custom_models', 'Custom models require Enterprise');
// Throws 403 if denied

// Trade history limit
const days = await getTradeHistoryLimit(userId);
// Returns: 30 | 365 | null (unlimited)

Plan Features

15. Plan Overrides (Gratuitous Subscriptions)

Admin-managed subscription overrides for trials, VIP users, and testing.

Override Schema

CREATE TABLE billing.user_plan_overrides (
  id              UUID PRIMARY KEY,
  user_id         UUID REFERENCES auth.users(id),
  plan_id         UUID REFERENCES billing.subscription_plans(id),
  granted_by      UUID REFERENCES auth.users(id),
  reason          TEXT CHECK (length(reason) >= 10),
  starts_at       TIMESTAMPTZ DEFAULT NOW(),
  expires_at      TIMESTAMPTZ,           -- NULL = open-ended
  revoked_at      TIMESTAMPTZ,           -- NULL = active
  revoked_by      UUID REFERENCES auth.users(id),
  created_at      TIMESTAMPTZ DEFAULT NOW()
);

Admin API Endpoints

Grant Override Request

POST /api/predict/v1/admin/users/{id}/plan-override
{
  "planId": "uuid",
  "reason": "Enterprise trial for evaluation (min 10 chars)",
  "expiresAt": "2026-06-19T00:00:00Z"
  // OR
  "durationHours": 720  // 30 days
}

Single-Active Invariant

When granting a new override, any existing active override is automatically revoked to prevent audit confusion.

16. File Reference

Complete file listing for authentication, onboarding, and authorization components.

Frontend Components

Frontend Stores

Backend Auth

Backend Handlers

License & Billing

Shared Types

Database Migrations