blueprint-platform/docs/consumption/demo-auth-routing-runbook.md

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.