# playchoo-auth

SwissOID authentication service for Playchoo. Manages OIDC login flow, session storage in Redis, and provides authentication endpoints for the Playchoo stack.

## Architecture

- **SwissOID Integration**: Uses `swissoid-back` for OIDC authorization code flow
- **Session Storage**: Redis-backed sessions with HttpOnly cookies
- **Shared Sessions**: `api.playchoo.com` and `app.playchoo.com` share session state via Redis

## Endpoints

- `GET /login` - Initiates SwissOID OIDC flow
- `POST /oidc/callback` - Handles SwissOID callback
- `GET /oidc/finalize` - Completes authentication and sets session cookie in first-party context
- `GET /auth/status` - Returns current authentication status
- `POST /auth/logout` - Destroys session
- `GET /auth/debug` - Debug endpoint to check session and cookie status
- `GET /auth/ping` - Connectivity test endpoint
- `GET /healthz` - Health check

## Environment Variables

```env
# SwissOID Configuration
SWISSOID_CLIENT_ID=playchoo
SWISSOID_CLIENT_SECRET=<your-secret>
SWISSOID_ISSUER=https://api.swissoid.com
SWISSOID_JWKS_URI=https://api.swissoid.com/.well-known/jwks.json
SWISSOID_TOKEN_ENDPOINT=https://api.swissoid.com/token
SWISSOID_AUTHORIZE_ENDPOINT=https://api.swissoid.com/authorize

# CORS
CORS_ALLOWED_ORIGIN=https://app.playchoo.com
CORS_CREDENTIALS=true
CORS_METHODS=GET,POST,OPTIONS
CORS_HEADERS=Content-Type,Authorization,Apollo-Require-Preflight,X-Requested-With,X-CSRF-Token
CORS_MAX_AGE=86400
SKIP_CORS=false

# Traefik / Deployment
REVERSE_DOMAIN=playchoo-auth
APPLICATION_DOMAIN_NAME=auth.playchoo.com

# Session Configuration
SESSION_COOKIE_NAME=playchoo_session
REFRESH_COOKIE_NAME=playchoo_refresh
SESSION_SECRET=<generate-random-secret>
STATE_SIGNING_SECRET=<generate-random-secret>
SESSION_TTL=7200
REFRESH_TTL=604800

# Redis (shared with py-playchoo-api)
REDIS_URL=redis://redis:6379

# RP Configuration
OIDC_REDIRECT_BASE_URL=https://auth.playchoo.com
RP_FRONTEND_URL=https://app.playchoo.com
RP_COOKIE_DOMAIN=.playchoo.com
POST_LOGIN_PATH=/dashboard
```

	> When running the service directly on your host (outside Docker), override
	> `REDIS_URL` to `redis://localhost:6379`. The Docker Compose files remap it to
	> `redis://redis:6379` so the container can reach the shared Redis service.

For production deploys copy `.env.prod` to the target host as `.env` (the compose
file loads `./.env`) and populate it with environment-specific secrets from
Vault before running the stack.

## Local Development

```bash
npm install

# Ensure the shared Redis network exists (run once)
docker network create playchoo_redis_network || true

# Start the Redis service from py-playchoo-api (or attach your own instance to the same network)
(cd ../py-playchoo-api && docker compose -f docker-compose.dev.yml up redis)

# In a new terminal, start the auth service
npm run dev
```

The service will start on `http://localhost:3700` and will reuse the Redis
container from `py-playchoo-api` through the `playchoo_redis_network` network.

## Docker

```bash
# Development
docker-compose -f docker-compose.dev.yml up

# Production
docker-compose up
```

## Session Format

Sessions stored in Redis under key `session:<sessionId>`:

```json
{
  "sub": "user-uuid-from-swissoid",
  "email": "user@example.com",
  "iat": 1234567890,
  "exp": 1234575090
}
```

## Integration

### Python API (py-playchoo-api)

The Python API reads sessions from the same Redis instance:

```python
# Retrieve session from cookie
session_id = request.cookies.get('playchoo_session')
session_data = redis_client.get(f'session:{session_id}')
user_uuid = json.loads(session_data)['sub']
```

### Frontend (playchoo-nextjs)

Uses `swissoid-front` React provider:

```tsx
import { SwissOIDAuthProvider } from 'swissoid-front';

<SwissOIDAuthProvider baseUrl="https://auth.playchoo.com">
  <App />
</SwissOIDAuthProvider>
```

## Related Documentation

- [`swissoid-back` README](../swissoid-back/README.md) - OIDC backend integration
- [`swissoid-front` README](../swissoid-front/README.md) - React frontend helpers
- [Playchoo API README](../py-playchoo-api/README.md) - Session lookup implementation