auth-pattern

# Enterprise Auth Pattern

Production-tested authentication and authorization patterns from IoT Admin Backend.

## When to Use

- Implementing JWT-based authentication
- Adding role-based access control (RBAC)
- Building realm-based permission systems
- Creating session state management
- Adding auth interceptors for API calls

## When NOT to Use

- Simple API key authentication (no roles needed)
- OAuth-only flows (use OAuth libraries instead)
- Serverless/stateless auth (no session needed)

---

## Quick Start

1. Choose auth pattern (JWT + Realms recommended)
2. Implement session state machine
3. Add auth interceptor for HTTP calls
4. Define realms and roles
5. Add route guards for protected pages
6. Test with positive/negative auth scenarios

---

## Core Patterns

### Pattern 1: Realm-Based Authorization

**The 3-tier hierarchy per resource:**

```
ADMIN ─┬─ Full access (create, read, update, delete, configure)
       │
EDIT  ─┼─ Modify access (create, read, update, delete)
       │
READ  ─┴─ View access (read only)
```

**Why this pattern diverges from standard RBAC:**
- Roles are scoped to realms (resources), not global
- Hierarchical inheritance (ADMIN includes EDIT, EDIT includes READ)
- Fine-grained without explosion of role combinations

**Implementation:**

```typescript
// Realm definition
export interface Realm {
  id: string;      // e.g., "users", "devices", "settings"
  name: string;
  roles: RealmRole[];
}

export enum RealmRole {
  ADMIN = 'admin',
  EDIT = 'edit',
  READ = 'read'
}

// User's realm assignments
export interface UserRealms {
  userId: string;
  realms: Realm[];
}

// Authorization check with hierarchy
function hasRole(userRealms: Realm[], realmId: string, requiredRole: RealmRole): boolean {
  const realm = userRealms.find(r => r.id === realmId);
  if (!realm) return false;

  // ADMIN has all permissions
  if (realm.roles.includes(RealmRole.ADMIN)) return true;

  // EDIT includes READ
  if (requiredRole === RealmRole.READ && realm