feat(satellite): add support for public backend URL in OAuth configuration

Author: Lasim

services/satellite/.env.example

@@ -6,6 +6,17 @@ LOG_LEVEL=debug
 # Backend Connection Configuration
 DEPLOYSTACK_BACKEND_URL=http://localhost:3000
 
+# Backend Public URL for OAuth (optional)
+# Use when satellite connects to backend via private network but MCP clients
+# need to reach backend via public internet URL.
+#
+# Example split-network setup:
+# - DEPLOYSTACK_BACKEND_URL=http://10.0.0.3:8080 (internal/private network)
+# - DEPLOYSTACK_BACKEND_PUBLIC_URL=https://cloud.deploystack.io (external/public)
+#
+# If not set, defaults to DEPLOYSTACK_BACKEND_URL (works for simple deployments)
+DEPLOYSTACK_BACKEND_PUBLIC_URL=
+
 # Satellite Public URL Configuration (REQUIRED for production OAuth)
 # This is the publicly accessible URL of this satellite instance
 # Used for OAuth 2.0 Protected Resource Metadata (RFC 9728)

services/satellite/src/middleware/auth-middleware.ts

@@ -173,10 +173,12 @@ export function requireScope(requiredScope: string) {
  */
 function sendAuthenticationRequired(reply: FastifyReply, _request: FastifyRequest) {
   const backendUrl = process.env.DEPLOYSTACK_BACKEND_URL || 'http://localhost:3000';
-  
+  // Public URL for OAuth - what MCP clients will use to reach the backend
+  const backendPublicUrl = process.env.DEPLOYSTACK_BACKEND_PUBLIC_URL || backendUrl;
+
   const wwwAuthenticate = `Bearer realm="DeployStack MCP Satellite", ` +
-    `authorizationUri="${backendUrl}/api/oauth2/auth", ` +
-    `tokenUri="${backendUrl}/api/oauth2/token", ` +
+    `authorizationUri="${backendPublicUrl}/api/oauth2/auth", ` +
+    `tokenUri="${backendPublicUrl}/api/oauth2/token", ` +
     `resource="deploystack:mcp:satellite"`;
 
   const errorResponse = {
@@ -186,8 +188,8 @@ function sendAuthenticationRequired(reply: FastifyReply, _request: FastifyReques
       message: 'Authentication required',
       data: {
         message: 'Bearer token required for MCP access',
-        authorization_uri: `${backendUrl}/api/oauth2/auth`,
-        token_uri: `${backendUrl}/api/oauth2/token`
+        authorization_uri: `${backendPublicUrl}/api/oauth2/auth`,
+        token_uri: `${backendPublicUrl}/api/oauth2/token`
       }
     },
     id: null

services/satellite/src/routes/oauth-discovery.ts

@@ -7,6 +7,9 @@ import { type FastifyInstance } from 'fastify';
  */
 export default async function oauthDiscoveryRoutes(server: FastifyInstance) {
   const backendUrl = process.env.DEPLOYSTACK_BACKEND_URL || 'http://localhost:3000';
+  // Public URL for OAuth metadata - what MCP clients will use to reach the backend
+  // Falls back to backendUrl for simple deployments where internal = external URL
+  const backendPublicUrl = process.env.DEPLOYSTACK_BACKEND_PUBLIC_URL || backendUrl;
   const satelliteUrl = process.env.DEPLOYSTACK_SATELLITE_URL || `http://localhost:${process.env.PORT || 3001}`;
 
   // RFC 9728: OAuth 2.0 Protected Resource Metadata
@@ -31,7 +34,7 @@ export default async function oauthDiscoveryRoutes(server: FastifyInstance) {
   }, async (request, reply) => {
     const metadata = {
       resource: satelliteUrl,
-      authorization_servers: [backendUrl]
+      authorization_servers: [backendPublicUrl]
     };
 
     server.log.debug({
@@ -81,15 +84,15 @@ export default async function oauthDiscoveryRoutes(server: FastifyInstance) {
     }
   }, async (request, reply) => {
     const metadata = {
-      issuer: backendUrl,
-      authorization_endpoint: `${backendUrl}/api/oauth2/auth`,
-      token_endpoint: `${backendUrl}/api/oauth2/token`,
-      introspection_endpoint: `${backendUrl}/api/oauth2/introspect`,
+      issuer: backendPublicUrl,
+      authorization_endpoint: `${backendPublicUrl}/api/oauth2/auth`,
+      token_endpoint: `${backendPublicUrl}/api/oauth2/token`,
+      introspection_endpoint: `${backendPublicUrl}/api/oauth2/introspect`,
       response_types_supported: ['code'],
       grant_types_supported: ['authorization_code'],
       code_challenge_methods_supported: ['S256'],
       scopes_supported: ['mcp:read', 'mcp:tools:execute', 'offline_access'],
-      registration_endpoint: `${backendUrl}/api/oauth2/register`
+      registration_endpoint: `${backendPublicUrl}/api/oauth2/register`
     };
 
     server.log.debug({
@@ -145,15 +148,15 @@ export default async function oauthDiscoveryRoutes(server: FastifyInstance) {
   }, async (request, reply) => {
     // Return the same metadata as OAuth authorization server for compatibility
     const metadata = {
-      issuer: backendUrl,
-      authorization_endpoint: `${backendUrl}/api/oauth2/auth`,
-      token_endpoint: `${backendUrl}/api/oauth2/token`,
-      introspection_endpoint: `${backendUrl}/api/oauth2/introspect`,
+      issuer: backendPublicUrl,
+      authorization_endpoint: `${backendPublicUrl}/api/oauth2/auth`,
+      token_endpoint: `${backendPublicUrl}/api/oauth2/token`,
+      introspection_endpoint: `${backendPublicUrl}/api/oauth2/introspect`,
       response_types_supported: ['code'],
       grant_types_supported: ['authorization_code'],
       code_challenge_methods_supported: ['S256'],
       scopes_supported: ['mcp:read', 'mcp:tools:execute', 'offline_access'],
-      registration_endpoint: `${backendUrl}/api/oauth2/register`
+      registration_endpoint: `${backendPublicUrl}/api/oauth2/register`
     };
 
     server.log.debug({