feat: add helpers and improve workspace auth flows

2026-07-13 13:53:36 +05:30
parent 88e907783a
commit b4e5fade19
74 changed files with 853 additions and 131 deletions
@@ -176,6 +176,19 @@ interface GatewaySecurity {
 }
 ```

+Forward auth is a verification hook, not a login page. Configure `forward.url` with a
+dedicated endpoint such as `http://sso.localhost:3000/api/verify`. The gateway forwards
+the request's `Cookie` and `Authorization` headers plus `X-Forwarded-Host`,
+`X-Forwarded-Proto`, `X-Original-Method`, and `X-Original-Uri` (including its query
+string). The verifier must return 2xx only for an authenticated session and 401/403
+otherwise. Pointing forward auth at an SSO home page that always returns 200 allows
+every request and does not implement SSO.
+
+For browser SSO, the verifier may return a `302`/`303`/`307`/`308` with a `Location`
+header pointing to its login page. The gateway passes that redirect to the browser. The
+login flow should validate a signed `returnTo` value before redirecting back; API clients
+should receive `401`/`403` instead of an HTML login redirect.
+
 Open the gateway URL (normally `http://127.0.0.1:3000`), not an app's internal
 port. The gateway exposes `/__gateway/health` (JSON list of routed apps) and returns a
 `RunningGateway` (`{ port, url, stop() }`). Use `--host=0.0.0.0` when other devices need