fix(oauth): bind port check to 127.0.0.1 to match callback server

checkPortAvailable() was binding to all interfaces (0.0.0.0), while
OAuthCallbackServer binds to 127.0.0.1. This mismatch caused false
positives when checking port 5173 availability while Vite dev server
was running on 127.0.0.1:5173.

The callback server would then fail with EADDRINUSE when trying to
bind to the same port on 127.0.0.1.

Changes:
- Add OAUTH_CALLBACK_HOST constant (127.0.0.1) with documentation
- Use constant in both checkPortAvailable() and OAuthCallbackServer
- Add debug logging with error code when port is unavailable

Author: gregdetre

src/auth/callbackServer.ts

@@ -1,6 +1,7 @@
 import * as http from "http";
 import { timingSafeEqual } from "crypto";
 import { getLogger } from "../logging.js";
+import { OAUTH_CALLBACK_HOST } from "../utils/portFinder.js";
 
 const logger = getLogger();
 
@@ -336,12 +337,11 @@ export class OAuthCallbackServer {
         }
       });
 
-      // Bind to loopback only to avoid triggering Windows Firewall prompts.
-      // Previously bound to all interfaces (0.0.0.0) which triggered firewall dialogs.
+      // Bind to OAUTH_CALLBACK_HOST (127.0.0.1) to avoid triggering Windows Firewall prompts.
       // Note: If users have issues with localhost resolving to ::1 (IPv6), we may need
       // to create dual listeners or ensure redirect URIs use 127.0.0.1 explicitly.
-      this.server.listen(this.port, '127.0.0.1', () => {
-        logger.info("OAuth callback server started", { port: this.port, host: '127.0.0.1' });
+      this.server.listen(this.port, OAUTH_CALLBACK_HOST, () => {
+        logger.info("OAuth callback server started", { port: this.port, host: OAUTH_CALLBACK_HOST });
         resolve();
       });
 

src/utils/portFinder.ts

@@ -3,6 +3,22 @@ import { getLogger } from "../logging.js";
 
 const logger = getLogger();
 
+/**
+ * The host address used for OAuth callback server binding.
+ * Using 127.0.0.1 (IPv4 loopback) to:
+ * - Avoid Windows Firewall prompts (binding to 0.0.0.0 triggers dialogs)
+ * - Ensure consistent behavior across platforms
+ * 
+ * Note: redirect_uris use "localhost" (see simple.ts), which typically resolves
+ * to 127.0.0.1 on most systems. If IPv6 issues arise (localhost -> ::1), we may
+ * need to align redirect_uris with this constant.
+ * 
+ * IMPORTANT: This constant must be used by both:
+ * - checkPortAvailable() in this file
+ * - OAuthCallbackServer.start() in callbackServer.ts
+ */
+export const OAUTH_CALLBACK_HOST = "127.0.0.1";
+
 /**
  * Find an available port starting from a given port number.
  * Tries consecutive ports until one is available or max attempts reached.
@@ -32,16 +48,25 @@ export async function findAvailablePort(
 }
 
 /**
- * Check if a specific port is available for binding.
+ * Check if a specific port is available for binding on OAUTH_CALLBACK_HOST.
+ * Must match the actual binding used by OAuthCallbackServer.
  */
 export function checkPortAvailable(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const server = net.createServer();
-    server.once("error", () => resolve(false));
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      logger.debug("Port unavailable", { 
+        port, 
+        host: OAUTH_CALLBACK_HOST,
+        code: err.code,
+        message: err.message 
+      });
+      resolve(false);
+    });
     server.once("listening", () => {
       server.close(() => resolve(true));
     });
-    // Bind to all interfaces (no host specified) to match callback server behavior
-    server.listen(port);
+    // Bind to OAUTH_CALLBACK_HOST to match OAuthCallbackServer behavior
+    server.listen(port, OAUTH_CALLBACK_HOST);
   });
 }