feat: Added OAuth Auth Code Flow for GH Codespaces (#223)

Author: christian-kreuzberger-dtx

CHANGELOG.md

@@ -2,10 +2,12 @@
 
 ## Unreleased Changes
 
+- Fixed OAuth callback URL to work in GitHub Codespaces by detecting the environment and using the forwarded URL instead of localhost
+- Breaking: Changed default HTTP server host binding from `0.0.0.0` to `127.0.0.1` for improved security
+
 ### Scopes
 
 - Removed scope `app-engine:functions:run` as it's not needed
-- Breaking: Changed default HTTP server host binding from `0.0.0.0` to `127.0.0.1` for improved security
 
 ## 0.11.0
 

src/authentication/dynatrace-oauth-auth-code-flow.test.ts

@@ -57,4 +57,50 @@ describe('OAuth Authorization Code Flow', () => {
     // Clean up
     result.server.close();
   });
+
+  test('startOAuthRedirectServer uses forwarded URL in GitHub Codespaces', async () => {
+    const originalEnv = process.env;
+
+    try {
+      // Mock Codespaces environment variables
+      process.env.CODESPACE_NAME = 'test-codespace';
+      process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+
+      const port = 8080;
+      const result = await startOAuthRedirectServer(port);
+
+      expect(result.redirectUri).toBe('https://test-codespace-8080.app.github.dev/auth/login');
+      expect(result.server).toBeDefined();
+      expect(result.waitForAuthorizationCode).toBeDefined();
+
+      // Clean up
+      result.server.close();
+    } finally {
+      // Restore original environment
+      process.env = originalEnv;
+    }
+  });
+
+  test('startOAuthRedirectServer falls back to localhost when not in Codespaces', async () => {
+    const originalEnv = process.env;
+
+    try {
+      // Ensure Codespaces environment variables are not set
+      delete process.env.CODESPACE_NAME;
+      delete process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN;
+
+      const port = 8080;
+      const result = await startOAuthRedirectServer(port);
+
+      expect(result.redirectUri).toBe('http://localhost:8080/auth/login');
+      expect(result.server).toBeDefined();
+      expect(result.waitForAuthorizationCode).toBeDefined();
+
+      // Clean up
+      result.server.close();
+    } finally {
+      // Restore original environment
+      process.env = originalEnv;
+    }
+  });
 });

src/authentication/dynatrace-oauth-auth-code-flow.ts

@@ -5,6 +5,7 @@ import { OAuthAuthorizationConfig, OAuthAuthorizationResult, OAuthTokenResponse
 import { requestOAuthToken } from './dynatrace-oauth-base';
 import { base64URLEncode, generateRandomState } from './utils';
 import open from 'open';
+import { getCodespacesForwardedUrl } from '../utils/environment-detection';
 
 /**
  * Generates PKCE code verifier and challenge according to RFC 7636
@@ -101,7 +102,9 @@ export async function startOAuthRedirectServer(port: number = 5344): Promise<{
   redirectUri: string;
   waitForAuthorizationCode: () => Promise<{ code: string; state: string }>;
 }> {
-  const redirectUri = `http://localhost:${port}/auth/login`;
+  // Check if we're running in GitHub Codespaces and use forwarded URL if so
+  const forwardedUrl = getCodespacesForwardedUrl(port);
+  const redirectUri = forwardedUrl ? `${forwardedUrl}/auth/login` : `http://localhost:${port}/auth/login`;
 
   let resolveAuthCode: (value: { code: string; state: string }) => void;
   let rejectAuthCode: (error: Error) => void;

src/utils/environment-detection.test.ts

@@ -0,0 +1,130 @@
+import { isRunningInCodespaces, getCodespacesForwardedUrl } from './environment-detection';
+
+describe('isRunningInCodespaces', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset environment variables before each test
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    // Restore original environment after each test
+    process.env = originalEnv;
+  });
+
+  it('should return true when both CODESPACE_NAME and GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN are set', () => {
+    process.env.CODESPACE_NAME = 'my-codespace';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+
+    expect(isRunningInCodespaces()).toBe(true);
+  });
+
+  it('should return false when CODESPACE_NAME is missing', () => {
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+    // CODESPACE_NAME is not set
+
+    expect(isRunningInCodespaces()).toBe(false);
+  });
+
+  it('should return false when GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN is missing', () => {
+    process.env.CODESPACE_NAME = 'my-codespace';
+    // GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN is not set
+
+    expect(isRunningInCodespaces()).toBe(false);
+  });
+
+  it('should return false when both environment variables are missing', () => {
+    // Neither CODESPACE_NAME nor GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN are set
+
+    expect(isRunningInCodespaces()).toBe(false);
+  });
+
+  it('should return false when CODESPACE_NAME is empty string', () => {
+    process.env.CODESPACE_NAME = '';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+
+    expect(isRunningInCodespaces()).toBe(false);
+  });
+
+  it('should return false when GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN is empty string', () => {
+    process.env.CODESPACE_NAME = 'my-codespace';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = '';
+
+    expect(isRunningInCodespaces()).toBe(false);
+  });
+});
+
+describe('getCodespacesForwardedUrl', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset environment variables before each test
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    // Restore original environment after each test
+    process.env = originalEnv;
+  });
+
+  it('should return the correct forwarded URL when running in Codespaces', () => {
+    process.env.CODESPACE_NAME = 'my-codespace';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+
+    const result = getCodespacesForwardedUrl(8080);
+
+    expect(result).toBe('https://my-codespace-8080.app.github.dev');
+  });
+
+  it('should return null when not running in Codespaces', () => {
+    // Neither environment variable is set
+
+    const result = getCodespacesForwardedUrl(8080);
+
+    expect(result).toBeNull();
+  });
+
+  it('should return null when CODESPACE_NAME is missing', () => {
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+
+    const result = getCodespacesForwardedUrl(8080);
+
+    expect(result).toBeNull();
+  });
+
+  it('should return null when GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN is missing', () => {
+    process.env.CODESPACE_NAME = 'my-codespace';
+
+    const result = getCodespacesForwardedUrl(8080);
+
+    expect(result).toBeNull();
+  });
+
+  it('should handle different port numbers correctly', () => {
+    process.env.CODESPACE_NAME = 'test-codespace';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'preview.app.github.dev';
+
+    expect(getCodespacesForwardedUrl(3000)).toBe('https://test-codespace-3000.preview.app.github.dev');
+    expect(getCodespacesForwardedUrl(5344)).toBe('https://test-codespace-5344.preview.app.github.dev');
+    expect(getCodespacesForwardedUrl(9999)).toBe('https://test-codespace-9999.preview.app.github.dev');
+  });
+
+  it('should handle codespace names with special characters', () => {
+    process.env.CODESPACE_NAME = 'my-special_codespace.v1';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'app.github.dev';
+
+    const result = getCodespacesForwardedUrl(8080);
+
+    expect(result).toBe('https://my-special_codespace.v1-8080.app.github.dev');
+  });
+
+  it('should handle different domain formats', () => {
+    process.env.CODESPACE_NAME = 'codespace-123';
+    process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN = 'githubpreview.dev';
+
+    const result = getCodespacesForwardedUrl(4000);
+
+    expect(result).toBe('https://codespace-123-4000.githubpreview.dev');
+  });
+});

src/utils/environment-detection.ts

@@ -0,0 +1,27 @@
+/**
+ * Utility functions for detecting and handling different runtime environments
+ */
+
+/**
+ * Detects if the application is running in GitHub Codespaces
+ * @returns true if running in Codespaces, false otherwise
+ */
+export function isRunningInCodespaces(): boolean {
+  return !!(process.env.CODESPACE_NAME && process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN);
+}
+
+/**
+ * Gets the forwarded URL for OAuth redirect in GitHub Codespaces
+ * @param port The port number to use in the forwarded URL
+ * @returns The forwarded URL if in Codespaces, null otherwise
+ */
+export function getCodespacesForwardedUrl(port: number): string | null {
+  if (!isRunningInCodespaces()) {
+    return null;
+  }
+
+  const codespaceName = process.env.CODESPACE_NAME!;
+  const domain = process.env.GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN!;
+
+  return `https://${codespaceName}-${port}.${domain}`;
+}