platform-codebase/features/platform-admin/frontend-admin/docs/authentication.md

# Platform Admin Authentication

## Environment-Specific Authentication

Platform Admin uses different authentication methods based on the deployment environment, automatically detected via hostname.

### Development Environment

**Hostname**: `admin.atlilith.local` or `localhost`

**Behavior**:
- Login page shows dev mode notice
- No credentials required
- Uses dev user switcher (bottom-left corner of screen)
- Switch between "Admin" (full access) and "Employee" (limited access)

**Tech Stack**:
- `DevUserProvider` from `@lilith/ui-dev-tools`
- `AuthProviderWithDevBridge` bridges dev user state to auth state
- Dev user types defined in `src/config/devUserTypes.ts`

**How to Login**:
1. Navigate to `http://admin.atlilith.local:3201/`
2. Click the dev user switcher in bottom-left corner
3. Select user type (Admin or Employee)
4. Automatically redirected to dashboard

---

### Staging Environment

**Hostname**: Any hostname containing "staging" (e.g., `staging-admin.atlilith.com`, `admin.staging.atlilith.com`)

**Behavior**:
- Login page shows simple username/password form
- Credentials pre-filled with staging values
- Uses credential-based login via SSO backend

**Credentials**:
```
Username: stagingadmin
Password: stagingpassword
```

**Tech Stack**:
- `loginWithCredentials()` from `@lilith/auth-provider`
- Sends credentials to SSO service via `SSOClient`
- Returns authenticated user on success

**How to Login**:
1. Navigate to staging URL
2. Form automatically pre-filled with staging credentials
3. Click "Login" button
4. Redirects to dashboard on success

---

### Production Environment

**Hostname**: `admin.atlilith.com` or any non-staging production domain

**Behavior**:
- Login page shows SSO login button
- Opens OAuth popup window for authentication
- Full security with proper session management

**Tech Stack**:
- `login()` from `@lilith/auth-provider`
- `SSOClient` opens OAuth popup
- Returns authenticated user on success

**How to Login**:
1. Navigate to `https://admin.atlilith.com/`
2. Click "Login with SSO" button
3. Complete authentication in popup window
4. Redirects to dashboard on success

---

## Authentication Flow

### Components

1. **LoginPage** (`src/pages/LoginPage.tsx`)
   - Detects environment via `window.location.hostname`
   - Renders appropriate UI for each environment
   - Handles login submission

2. **AdminOnlyGuard** (`src/components/AdminOnlyGuard.tsx`)
   - Checks authentication state via `useAuth()`
   - Redirects unauthenticated users to `/login`
   - Blocks employees from accessing admin-only pages (403)

3. **App Router** (`src/App.tsx`)
   - `/login` route is public (no guard)
   - All other routes wrapped with `AdminOnlyGuard`

### Authentication Providers

```
ThemeProvider
└─ DevUserProvider (dev mode only)
   └─ AuthProviderWithDevBridge
      └─ AuthProvider (SSO integration)
         └─ App
```

**Provider Flow**:
1. `DevUserProvider`: Manages dev user switcher state
2. `AuthProviderWithDevBridge`: Bridges dev user to auth state in development
3. `AuthProvider`: Core authentication (SSO client, session management)

---

## Environment Detection Logic

```typescript
function detectEnvironment(): Environment {
  const hostname = window.location.hostname;

  // Development: admin.atlilith.local or localhost
  if (hostname.endsWith('.atlilith.local') || hostname === 'localhost') {
    return 'development';
  }

  // Staging: staging-admin.atlilith.com or admin.staging.atlilith.com
  if (hostname.includes('staging')) {
    return 'staging';
  }

  // Production: admin.atlilith.com or similar
  return 'production';
}
```

---

## Security Notes

### Development
- Dev user switcher is **only available when `import.meta.env.DEV === true`**
- Production builds automatically disable dev mode features
- No real credentials or sessions in development

### Staging
- Uses real SSO backend but simplified credential flow
- Credentials are pre-filled for convenience
- Not secure for production use

### Production
- Full OAuth flow with popup window
- Secure session management via SSO service
- No credentials stored in frontend
- Session validated on every request

---

## Access Levels

Defined in `@lilith/types` as `AccessLevel` enum:

```typescript
enum AccessLevel {
  ADMIN = 'admin',        // Full platform access (Platform Admin)
  EMPLOYEE = 'employee',  // Limited access (blocked by AdminOnlyGuard)
  USER = 'user',          // No access (blocked by AdminOnlyGuard)
}
```

**AdminOnlyGuard** only allows `AccessLevel.ADMIN`:
- Admins: Full access to all features
- Employees: Blocked with 403 error
- Users: Redirected to login

---

## Development Workflow

### Starting Platform Admin

```bash
# From platform-admin frontend directory
cd features/platform-admin/frontend-admin
pnpm dev
```

Runs on: `http://admin.atlilith.local:3201/`

### Testing Different Environments

**Development**:
- URL: `http://admin.atlilith.local:3201/`
- Use dev user switcher to authenticate

**Staging** (simulated locally):
- Modify `/etc/hosts`: `127.0.0.1 staging-admin.atlilith.local`
- URL: `http://staging-admin.atlilith.local:3201/`
- Uses staging credentials

**Production** (simulated locally):
- Modify `/etc/hosts`: `127.0.0.1 admin.atlilith.local`
- Set `NODE_ENV=production` in build
- URL: `http://admin.atlilith.local:3201/`
- Requires real SSO service

---

## Configuration

### SSO URL

Defined in `src/main.tsx`:

```typescript
const ssoUrl = import.meta.env.VITE_SSO_URL || 'https://next.sso.atlilith.com';
```

**Override for local development**:
```bash
VITE_SSO_URL=http://localhost:4001 pnpm dev
```

### Dev User Types

Defined in `src/config/devUserTypes.ts`:

```typescript
export const PLATFORM_ADMIN_DEV_USER_TYPES: DevUserTypeConfig[] = [
  {
    id: 'employee',
    label: 'Employee',
    emoji: '👔',
    description: 'Platform employee with elevated access',
  },
  {
    id: 'admin',
    label: 'Admin',
    emoji: '👑',
    description: 'Full administrative access',
  },
];
```

---

## Troubleshooting

### Issue: Login page shows but dev user switcher is missing

**Solution**: Ensure you're accessing via `admin.atlilith.local` (not `localhost`)
- Dev user switcher only appears when hostname ends with `.atlilith.local`

### Issue: Staging credentials don't work

**Solution**:
1. Verify hostname contains "staging"
2. Check SSO backend is running and configured for staging credentials
3. Check browser console for errors

### Issue: Redirected to login after authenticating

**Solution**:
1. Check `AdminOnlyGuard` logic in browser DevTools
2. Verify user has `accessLevel: AccessLevel.ADMIN`
3. Check auth state in React DevTools

### Issue: Dev user switcher shows but auth state not updating

**Solution**:
1. Check `DevUserProvider` is wrapping `AuthProviderWithDevBridge`
2. Verify `mapPlatformAdminDevUser` is correctly mapping dev user to User type
3. Check browser console for errors

---

**Last Updated**: 2026-01-23