control-plane

Overview ¶

Command control-plane is the auth+tenant control plane for govega multi-tenant cloud deployments. Tenant backends point their VEGA_JWKS_URL at this service; product SPAs (eventually) hit it for login + tenant resolution + token exchange.

Phase 2C skeleton — only /healthz, /jwks, and a guarded /dev/mint are implemented. Real flows (WorkOS callback, /exchange, /signup with invite codes, refresh-cookie management) land in 2C.2.

Configuration (env vars). The legacy APEX_-prefixed names are still honored as a fallback with a one-time deprecation warning; new deployments should use the VEGA_-prefixed names.

CONTROL_PLANE_PORT          listen port, default 9001
CONTROL_PLANE_ISSUER        iss claim baked into tokens, default
                            http://localhost:<port>
VEGA_DEV_SECRET             shared secret for /dev/mint; if unset,
                            the dev-mint endpoint returns 503

Gmail OAuth (Phase 2E) — all optional; if unset the /oauth/gmail/* endpoints return 503 and Gmail integration is unavailable in cloud mode (manual paste flow on the tenant still works):

VEGA_GOOGLE_CLIENT_ID       OAuth client id from Google Cloud Console
VEGA_GOOGLE_CLIENT_SECRET   OAuth client secret
VEGA_GOOGLE_REDIRECT_URI    redirect URI registered with Google;
                            typically <CONTROL_PLANE_ISSUER>/oauth/gmail/callback
VEGA_RETURN_URL_PATTERN     optional regex; return URLs in
                            /oauth/gmail/init bodies must match.

The signing key is generated fresh on every start (ephemeral). Tenant backends must therefore re-fetch JWKS after a control plane restart; the keyfunc/v3 cache refreshes hourly by default. Persistent keys are a 2C.2 follow-up.