merge: integrate blueprint-platform auth and web updates

docs/architecture/platform-boundaries.md

@@ -20,3 +20,8 @@ This repository is a modular multi-package platform library set.
 - Identity abstractions are not owned by this repository.
 - Downstream repositories consume package contracts from this repo.
 - Secret provider abstractions are provider-agnostic; concrete provider adapters are bound at runtime.
+
+## Workspace Integration References
+
+- `docs/consumption/demo-auth-routing-runbook.md` defines centralized auth + demo host routing contracts.
+- `docs/consumption/demo-auth-routing-validation.md` defines post-change verification for routing and callback safety.

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

@@ -0,0 +1,77 @@
+# 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.

docs/consumption/demo-auth-routing-validation.md

@@ -0,0 +1,80 @@
+# Demo Auth Routing Validation
+
+## Scope
+
+Validate centralized auth routing and per-host API routing for demo stacks.
+
+## Prerequisites
+
+- Caddy is running on the VPS.
+- Demo stacks are running in Portainer.
+- DNS records point to the VPS for all demo hosts.
+
+## Caddy Validation
+
+```bash
+caddy validate --config /etc/caddy/Caddyfile
+```
+
+```bash
+sudo systemctl reload caddy
+```
+
+## Host Health Checks
+
+Run from any machine that can resolve public demo hosts:
+
+```bash
+curl -i https://auth.dream-views.com/health
+curl -i https://furniture-display-demo.dream-views.com/
+curl -i https://furniture-admin-demo.dream-views.com/
+curl -i https://kitchen-ops-demo.dream-views.com/
+curl -i https://waiter-floor-demo.dream-views.com/
+curl -i https://customer-orders-demo.dream-views.com/
+curl -i https://pos-transactions-demo.dream-views.com/
+curl -i https://restaurant-admin-demo.dream-views.com/
+```
+
+## Identity Route Checks
+
+```bash
+curl -i https://furniture-display-demo.dream-views.com/api/identity/session/me
+curl -i https://kitchen-ops-demo.dream-views.com/api/identity/session/me
+curl -i https://restaurant-admin-demo.dream-views.com/api/identity/session/me
+```
+
+Expected outcomes:
+- `200` when an authenticated session cookie is present.
+- `401` when no session cookie is present.
+- No `404` on identity paths.
+
+## Domain API Route Checks
+
+```bash
+curl -i "https://furniture-display-demo.dream-views.com/api/furniture/demo-context/availability"
+curl -i "https://kitchen-ops-demo.dream-views.com/api/kitchen/ops/board?contextId=demo-context"
+curl -i "https://waiter-floor-demo.dream-views.com/api/waiter/floor/assignments?contextId=demo-context"
+curl -i "https://customer-orders-demo.dream-views.com/api/customer/orders/status?contextId=demo-context"
+curl -i "https://pos-transactions-demo.dream-views.com/api/pos/transactions/summary?contextId=demo-context"
+curl -i "https://restaurant-admin-demo.dream-views.com/api/restaurant/admin/config?contextId=demo-context"
+```
+
+Expected outcomes:
+- Routed to the corresponding domain BFF.
+- No cross-domain path leakage.
+
+## Callback Journey Check
+
+1. Open one demo web host.
+2. Start Google login.
+3. Complete callback on `auth.dream-views.com`.
+4. Confirm return to same-origin route defined by `THALOS_DEFAULT_RETURN_URL`.
+
+Expected outcomes:
+- Callback does not redirect to external origins.
+- Session-enabled API calls succeed after login.
+
+## Regression Guard
+
+- Re-run smoke scripts for `greenfield/demo/furniture` and `greenfield/demo/restaurant` after routing changes.
+- Re-check all web containers can still load runtime config values.