eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
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>
2026-10-19 13:18:04 +08:00

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.