From 8b6f0f8aca3da4a2f5d9b4b76d21f155a53121c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Ren=C3=A9=20White=20Enciso?= Date: Wed, 11 Mar 2026 11:33:15 -0600 Subject: [PATCH] docs(blueprint-platform): add centralized demo auth routing runbooks --- docs/architecture/platform-boundaries.md | 5 ++ docs/consumption/demo-auth-routing-runbook.md | 77 ++++++++++++++++++ .../demo-auth-routing-validation.md | 80 +++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 docs/consumption/demo-auth-routing-runbook.md create mode 100644 docs/consumption/demo-auth-routing-validation.md diff --git a/docs/architecture/platform-boundaries.md b/docs/architecture/platform-boundaries.md index 8a01640..f83106b 100644 --- a/docs/architecture/platform-boundaries.md +++ b/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. diff --git a/docs/consumption/demo-auth-routing-runbook.md b/docs/consumption/demo-auth-routing-runbook.md new file mode 100644 index 0000000..c3c940f --- /dev/null +++ b/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. diff --git a/docs/consumption/demo-auth-routing-validation.md b/docs/consumption/demo-auth-routing-validation.md new file mode 100644 index 0000000..cbc44fe --- /dev/null +++ b/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.