# Demo Auth Routing Runbook

## Purpose

This runbook defines the centralized login routing contract used by demo environments.

- Browser applications are exposed by dedicated demo hosts.
- Session endpoints are routed through Thalos (`auth.dream-views.com` and identity API paths).
- Domain BFF APIs remain host-scoped by path.

## Active Public Hosts

| Host | Role |
|---|---|
| `auth.dream-views.com` | Central Thalos auth host |
| `furniture-display-demo.dream-views.com` | Furniture display web + furniture API + identity API |
| `furniture-admin-demo.dream-views.com` | Furniture admin web + furniture API + identity API |
| `kitchen-ops-demo.dream-views.com` | Kitchen web + kitchen API + identity API |
| `waiter-floor-demo.dream-views.com` | Waiter web + waiter API + identity API |
| `customer-orders-demo.dream-views.com` | Customer orders web + customer API + identity API |
| `pos-transactions-demo.dream-views.com` | POS web + POS API + identity API |
| `restaurant-admin-demo.dream-views.com` | Restaurant admin web + admin API + identity API |

## Routing Contract

### 1. Central Auth Host

`auth.dream-views.com` proxies directly to Thalos BFF runtime (`127.0.0.1:20080`).

Use cases:
- OIDC launch endpoints (for example `/api/identity/oidc/google/start`)
- OIDC callback endpoints
- Session endpoints (`/api/identity/session/*`)

### 2. Demo Host Path Routing

For each demo host:

- `/api/identity/session*` -> Thalos session upstream
- domain-specific API paths -> domain BFF upstream
- all other paths -> web SPA upstream

### 3. Domain Path Scopes

| Host | Domain API Path Prefix |
|---|---|
| `furniture-display-demo.dream-views.com` | `/api/furniture*` |
| `furniture-admin-demo.dream-views.com` | `/api/furniture*` |
| `kitchen-ops-demo.dream-views.com` | `/api/kitchen/ops*` |
| `waiter-floor-demo.dream-views.com` | `/api/waiter/floor*` |
| `customer-orders-demo.dream-views.com` | `/api/customer/orders*` |
| `pos-transactions-demo.dream-views.com` | `/api/pos/transactions*` |
| `restaurant-admin-demo.dream-views.com` | `/api/restaurant/admin*` |

## Web Runtime Configuration Contract

All web containers must provide:

- `API_BASE_URL`: same-origin default for domain API calls
- `THALOS_AUTH_BASE_URL`: centralized auth base (typically same host or `auth.dream-views.com`)
- `THALOS_DEFAULT_RETURN_URL`: safe same-origin callback target
- `THALOS_DEFAULT_TENANT_ID`: tenant context default

## Safety Rules

- Callback return targets must be sanitized to same-origin paths.
- Identity routes are always Thalos-owned.
- No direct DAL access from web clients.
- No cross-repo `ProjectReference` exceptions are introduced by routing changes.

## Change Workflow

1. Update Caddy site entries under `/etc/caddy/sites-enabled/*.caddy`.
2. Validate Caddy config before reload.
3. Reload Caddy.
4. Run demo auth-routing validation checklist (see `docs/consumption/demo-auth-routing-validation.md`).
5. Record route changes in this runbook in the same change set.