Authorization Model Defined

Ad-hoc role checks scattered across route files — user.role === 'admin' repeated in a dozen places — are impossible to audit and trivially out of sync. When a new role is added or a permission is tightened, every scattered comparison must be found and updated manually. One missed file is a silent privilege escalation. CWE-284 (Improper Access Control) and OWASP A01 (Broken Access Control) both trace back to exactly this pattern: authorization decisions made without a single, auditable source of truth. NIST 800-53 AC-3 requires access enforcement to be consistently applied — string comparisons in individual handlers fail that standard by design.

Create lib/auth/permissions.ts as the single source of truth for all role definitions and permission checks. Export a typed hasPermission(user, action) helper and import it from every route handler — never compare role strings inline again.

// lib/auth/permissions.ts
export const ROLES = { ADMIN: 'admin', MEMBER: 'member', VIEWER: 'viewer' } as const;
export type Role = typeof ROLES[keyof typeof ROLES];

export function hasPermission(user: { role: Role }, action: string): boolean {
  const permissions: Record<Role, string[]> = {
    admin: ['read', 'write', 'delete', 'manage_users'],
    member: ['read', 'write'],
    viewer: ['read'],
  };
  return permissions[user.role]?.includes(action) ?? false;
}

After adding this file, grep for user.role === across the codebase and replace every hit with a hasPermission() call.