Roles and Permissions

Related docs: SDLC/REQUIREMENTS · SDLC/DEVELOPMENT · Security Compliance

---

1. Role Hierarchy

Pakashop implements a comprehensive Role-Based Access Control (RBAC) system with 12 distinct roles. Roles are stored on the User.role field and enforced via middleware.

Role	ID	Description	MFA Required
CUSTOMER	customer	End consumer; browses, purchases, tracks orders	Optional
SHOP_OWNER	shop_owner	Vendor with approved shop; manages products, inventory, orders	Mandatory
SERVICE_PROVIDER	service_provider	Service-based vendor (e.g., repairs, consultations)	Optional
DELIVERY_AGENT	delivery_agent	Individual or courier company driver; manages deliveries	Mandatory
PLATFORM_ADMIN	platform_admin	Full platform administration; user management, system config	Mandatory
MODERATOR	moderator	Content moderation; reviews flagged images, products	Mandatory
FRAUD_ANALYST	fraud_analyst	Reviews fraud detection queue; approves/rejects blocked payments	Mandatory
FINANCE_ADMIN	finance_admin	Financial operations; settlements, reconciliation, payouts	Mandatory
SUPPORT_AGENT	support_agent	Customer support; views orders, handles tickets	Optional
SELLER	seller	Pending seller application; limited access until approved	Optional
FLEET_MANAGER	fleet_manager	Courier company admin; manages sub-agents, fleet operations	Mandatory
SYSTEM	system	Internal system role; used by automated jobs, cron tasks	N/A

---

2. Permissions Matrix

Legend

• F Full access
• 📝 Own resources only
• 👁️ Read-only
• ❌ No access

2.1 Core Business Operations

Permission	CUSTOMER	SHOP_OWNER	SERVICE_PROVIDER	DELIVERY_AGENT	PLATFORM_ADMIN	MODERATOR	FRAUD_ANALYST	FINANCE_ADMIN	SUPPORT_AGENT	SELLER	FLEET_MANAGER	SYSTEM
Browse products	F	F	F	F	F	F	F	F	F	F	F	F
Place orders	F	F	F	F	F	F	F	F	F	F	F	F
View own orders	F	📝	📝	📝	F	👁️	👁️	👁️	📝	📝	📝	F
Cancel own order	F	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Manage cart	F	F	F	F	F	F	F	F	F	F	F	F
Apply coupons	F	F	F	F	F	F	F	F	F	F	F	F
Redeem loyalty points	F	F	F	F	F	F	F	F	F	F	F	F

2.2 Vendor Operations

Permission	CUSTOMER	SHOP_OWNER	SERVICE_PROVIDER	DELIVERY_AGENT	PLATFORM_ADMIN	MODERATOR	FRAUD_ANALYST	FINANCE_ADMIN	SUPPORT_AGENT	SELLER	FLEET_MANAGER	SYSTEM
Create products	❌	📝	📝	❌	F	❌	❌	❌	❌	❌	❌	F
Edit own products	❌	📝	📝	❌	F	❌	❌	❌	❌	❌	❌	F
Delete own products	❌	📝	📝	❌	F	❌	❌	❌	❌	❌	❌	F
Manage inventory	❌	📝	📝	❌	F	❌	❌	❌	❌	❌	❌	F
View own shop analytics	❌	📝	📝	❌	F	❌	❌	👁️	❌	❌	❌	F
Set wholesale tiers	❌	📝	❌	❌	F	❌	❌	❌	❌	❌	❌	F
View own settlements	❌	📝	📝	❌	F	❌	❌	👁️	❌	❌	❌	F
Submit seller application	❌	❌	❌	❌	❌	❌	❌	❌	❌	F	❌	❌

2.3 Delivery Operations

Permission	CUSTOMER	SHOP_OWNER	SERVICE_PROVIDER	DELIVERY_AGENT	PLATFORM_ADMIN	MODERATOR	FRAUD_ANALYST	FINANCE_ADMIN	SUPPORT_AGENT	SELLER	FLEET_MANAGER	SYSTEM
Apply as delivery agent	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	❌	❌
Toggle availability	❌	❌	❌	📝	F	❌	❌	❌	❌	❌	📝	F
View assigned deliveries	❌	❌	❌	📝	F	❌	❌	❌	❌	❌	📝	F
Confirm delivery (PIN)	❌	❌	❌	📝	F	❌	❌	❌	❌	❌	❌	F
Capture digital signature	❌	❌	❌	📝	F	❌	❌	❌	❌	❌	❌	F
Manage fleet sub-agents	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	📝	❌
View delivery tracking	📝	📝	📝	📝	F	❌	❌	❌	📝	❌	📝	F

2.4 Admin Operations

Permission	CUSTOMER	SHOP_OWNER	SERVICE_PROVIDER	DELIVERY_AGENT	PLATFORM_ADMIN	MODERATOR	FRAUD_ANALYST	FINANCE_ADMIN	SUPPORT_AGENT	SELLER	FLEET_MANAGER	SYSTEM
Manage users	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Manage roles	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Approve seller applications	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Moderate content	❌	❌	❌	❌	F	F	❌	❌	❌	❌	❌	F
Review fraud queue	❌	❌	❌	❌	F	❌	F	❌	❌	❌	❌	F
Release settlements	❌	❌	❌	❌	F	❌	❌	F	❌	❌	❌	F
View reconciliation reports	❌	❌	❌	❌	F	❌	❌	F	❌	❌	❌	F
Send broadcast notifications	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Manage feature flags	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
View platform analytics	❌	❌	❌	❌	F	❌	❌	F	❌	❌	❌	F
Manage ZRA invoicing config	❌	❌	❌	❌	F	❌	❌	F	❌	❌	❌	F
Generate reports	❌	📝	📝	❌	F	❌	❌	F	❌	❌	❌	F
View all orders	❌	❌	❌	❌	F	❌	❌	👁️	📝	❌	❌	F
Cancel any order	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Approve/reject delivery agents	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F
Suspend/activate delivery agents	❌	❌	❌	❌	F	❌	❌	❌	❌	❌	❌	F

2.5 System Operations

Permission	CUSTOMER	SHOP_OWNER	SERVICE_PROVIDER	DELIVERY_AGENT	PLATFORM_ADMIN	MODERATOR	FRAUD_ANALYST	FINANCE_ADMIN	SUPPORT_AGENT	SELLER	FLEET_MANAGER	SYSTEM
Execute cron jobs	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	F
Process BullMQ jobs	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	F
Trigger database migrations	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	F
Access internal API endpoints	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	F

---

3. Role Constraints and Business Rules

3.1 Mutually Exclusive Roles

The following role combinations are prohibited to prevent conflicts of interest:

Role A	Cannot Also Be	Reason
PLATFORM_ADMIN	SHOP_OWNER, DELIVERY_AGENT	Prevents admin abuse of marketplace position
SHOP_OWNER	DELIVERY_AGENT	Prevents shipping conflicts of interest
DELIVERY_AGENT	SHOP_OWNER	Same as above
SELLER	SHOP_OWNER	SELLER is a transitional role; becomes SHOP_OWNER on approval

3.2 Role Transition Flow

SELLER
  │
  ▼ (admin approves application)
SHOP_OWNER
  │
  ▼ (can request additional role)
SERVICE_PROVIDER (optional dual-role)

CUSTOMER
  │
  ▼ (submits delivery application)
DELIVERY_AGENT
  │
  ▼ (assigned to courier company)
FLEET_MANAGER (if company admin)

3.3 MFA Enforcement

Role Category	MFA Required	Methods
Elevated (PLATFORM_ADMIN, SHOP_OWNER, DELIVERY_AGENT, MODERATOR, FRAUD_ANALYST, FINANCE_ADMIN, FLEET_MANAGER)	Mandatory	TOTP (speakeasy), Email OTP, SMS (Twilio)
Standard (CUSTOMER, SERVICE_PROVIDER, SUPPORT_AGENT)	Optional	TOTP, Email OTP
Transitional (SELLER)	N/A	Not applicable until role upgrade
System (SYSTEM)	N/A	Internal API key authentication

---

4. Implementation

4.1 Middleware

// middleware/rbac.js
const ROLE_HIERARCHY = {
  system: 100,
  platform_admin: 90,
  finance_admin: 80,
  fraud_analyst: 75,
  moderator: 70,
  fleet_manager: 65,
  shop_owner: 60,
  service_provider: 55,
  delivery_agent: 50,
  support_agent: 40,
  customer: 10,
  seller: 5,
};

const MUTUALLY_EXCLUSIVE = [
  ['platform_admin', 'shop_owner'],
  ['platform_admin', 'delivery_agent'],
  ['shop_owner', 'delivery_agent'],
];

const requireRoles = (...allowedRoles) => {
  return (req, res, next) => {
    const userRole = req.user.role;

    if (!allowedRoles.includes(userRole)) {
      return res.status(403).json({
        success: false,
        code: 'AUTH_002',
        message: 'Insufficient permissions'
      });
    }

    next();
  };
};

const requireMfa = (req, res, next) => {
  const elevatedRoles = [
    'platform_admin', 'shop_owner', 'delivery_agent',
    'moderator', 'fraud_analyst', 'finance_admin', 'fleet_manager'
  ];

  if (elevatedRoles.includes(req.user.role) && !req.user.mfaVerified) {
    return res.status(403).json({
      success: false,
      code: 'MFA_001',
      message: 'Multi-factor authentication required'
    });
  }

  next();
};

module.exports = { requireRoles, requireMfa, ROLE_HIERARCHY };

4.2 Route Usage

// routes/admin.js
const { requireRoles } = require('../middleware/rbac');

router.get('/users',
  authenticate,
  requireRoles('PLATFORM_ADMIN'),
  adminController.listUsers
);

router.patch('/seller-applications/:id/approve',
  authenticate,
  requireMfa,
  requireRoles('PLATFORM_ADMIN', 'MODERATOR'),
  adminController.approveSeller
);

router.get('/fraud-queue',
  authenticate,
  requireMfa,
  requireRoles('PLATFORM_ADMIN', 'FRAUD_ANALYST'),
  fraudController.listQueue
);

---

5. SYSTEM Role

The SYSTEM role is reserved for automated processes and should never be assigned to human users.

5.1 Use Cases

• Cron job execution (scheduler service)
• BullMQ job processing
• Database migration triggers
• Internal service-to-service communication
• Automated report generation
• Settlement batch processing

5.2 Authentication

SYSTEM role requests authenticate via the x-internal-key header (not JWT cookies):

// middleware/internal-auth.js
const authenticateInternal = (req, res, next) => {
  const internalKey = req.headers['x-internal-key'];

  if (internalKey !== process.env.INTERNAL_API_KEY) {
    return res.status(401).json({
      success: false,
      code: 'AUTH_003',
      message: 'Invalid internal API key'
    });
  }

  req.user = { role: 'SYSTEM', id: 'system' };
  next();
};

---

For internal use only. Do not distribute outside Pakashop engineering.