Imports the previously untracked working tree as-is so that the review changes that follow (requirements -> design -> implementation) can be reviewed as diffs and reverted if needed. No content changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.3 KiB
Workspace authorization gateway
This separate service protects the Theia HTTP and WebSocket boundary. Start with
npm ci && npm start in this directory and environment variables:
WF_API_URL=http://127.0.0.1:4000
WF_TENANT_ID=demo
WF_WORKSPACE_GATEWAY_TOKEN=<generated scoped service token>
WF_IDE_PUBLIC_URL=http://127.0.0.1:4400
WF_IDE_ALLOWED_UPSTREAM_ORIGINS=http://127.0.0.1:4300
POST /launch accepts a user Bearer token and {workspaceId}. The web server
relays this call using its encrypted session, then redirects to the returned
launchUrl. The URL contains a 30-second single-use random code, never the user
token. GET /session?code=... reauthorizes, consumes the code, sets an opaque
HttpOnly/SameSite cookie and redirects to /workspaces/:id/. Use HTTPS in production
for Secure cookies. Proxy/access logs must redact the launch-code query string.
Every HTTP request and WebSocket handshake calls the control plane's
POST /internal/workspaces/:id/authorize with the dedicated service token,
fixed X-WishForge-Tenant, and {userToken, operation}. Open WebSockets recheck
authorization every second with a 3-second authorization timeout (at most about
4 seconds until a changed grant or unavailable authorization service is observed)
and close on rejection, expiry, moved upstream or unavailable control plane.
User credentials and browser cookies are stripped before proxying. Theia 1.76's
separate theia-connection-token is captured from the allowed upstream and kept
server-side for subsequent HTTP/WebSocket proxy requests; it is never forwarded
to the browser. Upstream URLs must
come from the control-plane grant and also match the configured origin allowlist.
Viewers cannot enter the editing surface, even when an upstream mistakenly returns
a viewer grant. Multiplexed Theia services always require edit permission; callers
cannot select a weaker preview operation.
The production deployment must make Theia inaccessible except through this gateway. Use one tenant-bound gateway configuration per tenant. Sessions and codes currently live in process memory; restart requires relaunch and multiple replicas require a shared session store or affinity. The gateway does not persist OCT rooms or enforce fine-grained DAP controller leases/save barriers. The scoped collaboration route proxies HTTP/Socket.IO to a dedicated OCT instance from the grant, using edit authorization on each request and active socket revocation. It must be the only reachable network entry to that instance; production CNI isolation still requires an actual cluster test.
Tests use real local HTTP/WebSocket servers and cover credentials, replay, viewer denial, upstream allowlisting, origin checks and active connection revocation. The actual Theia asset/service/WebSocket/editor/terminal path was tested through the real control plane with local development authentication. Production OIDC login and project-bound collaboration require separate acceptance.
WF_COLLABORATION_ALLOWED_UPSTREAM_ORIGINS is a separate explicit local allowlist.
With WF_IDE_ALLOWED_SERVICE_NAMESPACE, managed IDE services must match exactly
wf-ide-<24 hex>.<namespace>.svc:3000 and collaboration uses that same service
name on 8100. Public clients cannot select the upstream URL. Theia's own process
cookie is cached by upstream and is never forwarded to the collaboration instance.