fix: address review feedback on BYOK support

- Reword docker-manager comment to clarify placeholder behavior
  when api-proxy is enabled
- Update github-copilot example to accept either COPILOT_GITHUB_TOKEN
  or COPILOT_API_KEY instead of hard-requiring COPILOT_API_KEY
- Extract resolveCopilotAuthToken() as a testable function with
  JSDoc and export it from server.js
- Add 8 unit tests covering precedence, fallback, empty/whitespace
  handling, and trimming behavior

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lpcox

containers/api-proxy/server.js

@@ -63,8 +63,20 @@ const OPENAI_API_KEY = (process.env.OPENAI_API_KEY || '').trim() || undefined;
 const ANTHROPIC_API_KEY = (process.env.ANTHROPIC_API_KEY || '').trim() || undefined;
 const COPILOT_GITHUB_TOKEN = (process.env.COPILOT_GITHUB_TOKEN || '').trim() || undefined;
 const COPILOT_API_KEY = (process.env.COPILOT_API_KEY || '').trim() || undefined;
-// BYOK: use COPILOT_GITHUB_TOKEN (GitHub OAuth) or COPILOT_API_KEY (direct key), GitHub token takes precedence
-const COPILOT_AUTH_TOKEN = COPILOT_GITHUB_TOKEN || COPILOT_API_KEY;
+
+/**
+ * Resolves the Copilot auth token from environment variables.
+ * COPILOT_GITHUB_TOKEN (GitHub OAuth) takes precedence over COPILOT_API_KEY (direct key).
+ * @param {Record<string, string|undefined>} env - Environment variables to inspect
+ * @returns {string|undefined} The resolved auth token, or undefined if neither is set
+ */
+function resolveCopilotAuthToken(env = process.env) {
+  const githubToken = (env.COPILOT_GITHUB_TOKEN || '').trim() || undefined;
+  const apiKey = (env.COPILOT_API_KEY || '').trim() || undefined;
+  return githubToken || apiKey;
+}
+
+const COPILOT_AUTH_TOKEN = resolveCopilotAuthToken(process.env);
 const GEMINI_API_KEY = (process.env.GEMINI_API_KEY || '').trim() || undefined;
 
 /**
@@ -999,4 +1011,4 @@ if (require.main === module) {
 }
 
 // Export for testing
-module.exports = { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket };
+module.exports = { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket, resolveCopilotAuthToken };

containers/api-proxy/server.test.js

@@ -5,7 +5,7 @@
 const http = require('http');
 const tls = require('tls');
 const { EventEmitter } = require('events');
-const { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket } = require('./server');
+const { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket, resolveCopilotAuthToken } = require('./server');
 
 describe('normalizeApiTarget', () => {
   it('should strip https:// prefix', () => {
@@ -620,3 +620,43 @@ describe('proxyWebSocket', () => {
   });
 });
 
+describe('resolveCopilotAuthToken', () => {
+  it('should return COPILOT_GITHUB_TOKEN when only it is set', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_GITHUB_TOKEN: 'gho_abc123' })).toBe('gho_abc123');
+  });
+
+  it('should return COPILOT_API_KEY when only it is set', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_API_KEY: 'sk-byok-key' })).toBe('sk-byok-key');
+  });
+
+  it('should prefer COPILOT_GITHUB_TOKEN over COPILOT_API_KEY when both are set', () => {
+    expect(resolveCopilotAuthToken({
+      COPILOT_GITHUB_TOKEN: 'gho_abc123',
+      COPILOT_API_KEY: 'sk-byok-key',
+    })).toBe('gho_abc123');
+  });
+
+  it('should return undefined when neither is set', () => {
+    expect(resolveCopilotAuthToken({})).toBeUndefined();
+  });
+
+  it('should return undefined for empty strings', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_GITHUB_TOKEN: '', COPILOT_API_KEY: '' })).toBeUndefined();
+  });
+
+  it('should return undefined for whitespace-only values', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_GITHUB_TOKEN: '  ', COPILOT_API_KEY: '  \n' })).toBeUndefined();
+  });
+
+  it('should trim whitespace from token values', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_API_KEY: '  sk-byok-key  ' })).toBe('sk-byok-key');
+  });
+
+  it('should fall back to COPILOT_API_KEY when COPILOT_GITHUB_TOKEN is whitespace-only', () => {
+    expect(resolveCopilotAuthToken({
+      COPILOT_GITHUB_TOKEN: '  ',
+      COPILOT_API_KEY: 'sk-byok-key',
+    })).toBe('sk-byok-key');
+  });
+});
+

examples/github-copilot.sh

@@ -6,7 +6,7 @@
 #
 # Prerequisites:
 # - GitHub Copilot CLI installed: npm install -g @github/copilot
-# - COPILOT_API_KEY environment variable set (for API proxy)
+# - COPILOT_GITHUB_TOKEN or COPILOT_API_KEY environment variable set (for API proxy)
 # - GITHUB_TOKEN environment variable set (for GitHub API access)
 #
 # Usage: sudo -E ./examples/github-copilot.sh
@@ -16,10 +16,12 @@ set -e
 echo "=== AWF GitHub Copilot CLI Example (with API Proxy) ==="
 echo ""
 
-# Check for COPILOT_API_KEY
-if [ -z "$COPILOT_API_KEY" ]; then
-  echo "Error: COPILOT_API_KEY environment variable is not set"
-  echo "Set it with: export COPILOT_API_KEY='your_copilot_api_key'"
+# Check for Copilot credential (COPILOT_GITHUB_TOKEN or COPILOT_API_KEY)
+if [ -z "$COPILOT_GITHUB_TOKEN" ] && [ -z "$COPILOT_API_KEY" ]; then
+  echo "Error: No Copilot credential set"
+  echo "Set one of:"
+  echo "  export COPILOT_GITHUB_TOKEN='your_github_token'"
+  echo "  export COPILOT_API_KEY='your_copilot_api_key'"
   exit 1
 fi
 
@@ -37,8 +39,8 @@ echo "Running GitHub Copilot CLI with API proxy and debug logging enabled..."
 echo ""
 
 # Run Copilot CLI with API proxy enabled
-# Use sudo -E to preserve environment variables (COPILOT_API_KEY, GITHUB_TOKEN, AWF_ONE_SHOT_TOKEN_DEBUG)
-# The api-proxy sidecar holds the real COPILOT_API_KEY and injects it into requests.
+# Use sudo -E to preserve environment variables (COPILOT_GITHUB_TOKEN, COPILOT_API_KEY, GITHUB_TOKEN, AWF_ONE_SHOT_TOKEN_DEBUG)
+# The api-proxy sidecar holds the real Copilot credential and injects it into requests.
 # Required domains:
 # - api.githubcopilot.com: Copilot API endpoint (proxied via api-proxy)
 # - github.com: GitHub API access

src/docker-manager.ts

@@ -747,7 +747,8 @@ export function generateDockerCompose(
     // it gets a placeholder value set earlier (line ~362) for credential isolation
     if (process.env.COPILOT_GITHUB_TOKEN && !config.enableApiProxy) environment.COPILOT_GITHUB_TOKEN = process.env.COPILOT_GITHUB_TOKEN;
     // COPILOT_API_KEY (BYOK) — forward when api-proxy is NOT enabled; when api-proxy IS enabled,
-    // it is excluded from agent env (held securely in api-proxy sidecar)
+    // the real key is not forwarded to the agent env and a placeholder may still be present
+    // for credential isolation while the real key is held securely in the api-proxy sidecar
     if (process.env.COPILOT_API_KEY && !config.enableApiProxy) environment.COPILOT_API_KEY = process.env.COPILOT_API_KEY;
     if (process.env.USER) environment.USER = process.env.USER;
     // When --tty is set, we use TERM=xterm-256color (set above); otherwise inherit host TERM