atlilith/@platform/codebase/@features/sso/backend-api/README.md

# SSO Service

Single Sign-On authentication service for lilith-platform.

## Features

- Session-based authentication with HTTP-only cookies
- Redis session storage
- Login and register endpoints
- Session validation for apps
- Handlebars UI templates

## Endpoints

### Authentication API

- `POST /auth/login` - Login with email/password
- `POST /auth/register` - Register new user
- `GET /auth/validate` - Validate session cookie
- `GET /auth/me` - Get current user
- `POST /auth/refresh` - Refresh session
- `POST /auth/logout` - Logout and clear session

### UI Pages

- `GET /login` - Login page
- `GET /register` - Register page

## Setup

1. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Install dependencies:
   ```bash
   pnpm install
   ```

3. Start Redis (required):
   ```bash
   docker-compose up redis
   ```

4. Start development server:
   ```bash
   pnpm start:dev
   ```

5. Access:
   - Service: http://localhost:4001
   - Login: http://localhost:4001/login
   - Register: http://localhost:4001/register

## Environment Variables

See `.env.example` for required configuration.

## Integration

Apps integrate by:
1. Redirecting to `/login` or `/register` (in popup or iframe)
2. Receiving `AUTH_SUCCESS` postMessage on completion
3. Making requests with `credentials: 'include'` to include cookies
4. Validating sessions via `GET /auth/validate`

## Docker

Build:
```bash
docker build -t lilith-sso .
```

Run:
```bash
docker run -p 4001:4001 --env-file .env lilith-sso
```

## Staging Deployment

**URL**: `https://next.sso.atlilith.com`
**Server**: black (10.0.0.11 via VPN)

### Server Paths

```
/opt/sso/                          # Application root
├── .env                           # Application secrets
├── .env.docker                    # Docker compose environment
├── backend-api/
│   └── src/ui/                    # Handlebars views (deployed via rsync)
└── infrastructure/
    └── ports.yaml                 # Port configuration
```

### Docker Services

| Service | Port | Container |
|---------|------|-----------|
| PostgreSQL | 5440 | sso-postgres |
| Redis | 6386 | sso-redis |

### Nginx Configuration

Located at `/bigdisk/forgejo/nginx.conf` (inside Forgejo container).

**Important**: Nginx proxies to `172.17.0.1:4001` (Docker bridge gateway IP) since SSO runs on the host, not in a container.

### SSL

Self-signed certificate at:
- `/bigdisk/forgejo/ssl/next.sso.atlilith.com.crt`
- `/bigdisk/forgejo/ssl/next.sso.atlilith.com.key`

### DNS

A record managed via PowerDNS API:
- `next.sso.atlilith.com` → `10.0.0.11`

### Updating Staging

```bash
# SSH to staging
ssh black

# Update code
cd /opt/sso && git pull

# Restart service
systemctl restart sso

# Deploy UI views (from local)
rsync -avz codebase/features/sso/backend-api/src/ui/ black:/opt/sso/backend-api/src/ui/
```

### Required Environment Variables

See `.env.example`. Critical secrets for staging:
- `MFA_ENCRYPTION_KEY` - 64-char hex
- `SESSION_SECRET` - 32-char random
- `DATABASE_POSTGRES_PASSWORD` - Hex format (avoid URL-breaking chars)
- `DATABASE_REDIS_PASSWORD` - 32-char random
- `CSRF_SECRET` - 32-char random
- `OAUTH_ENCRYPTION_SECRET` - 64-char hex