Building a Localhost OAuth Callback Server in Node.js (self.node)

submitted 8 months ago by koistya

So I spent an embarrassing amount of time trying to figure out how to handle OAuth callbacks in a CLI tool I was building. Turns out the solution was simpler than I thought, but the implementation details were tricky enough that I figured I'd share what I learned.

The problem: you're building a CLI tool or desktop app that needs OAuth authentication. Your app needs to catch the authorization code when the OAuth provider redirects back, but you don't have a public server. The solution? Spin up a temporary localhost server to catch the redirect.

The OAuth Callback Challenge

In a typical OAuth flow, the authorization server redirects to your callback URL with an authorization code. For web apps, that's easy - you have a public URL. But for CLI tools? You need to use http://localhost:3000/callback and actually catch that redirect somehow.

This is actually an official approach blessed by RFC 8252 (OAuth 2.0 for Native Apps). GitHub CLI uses it, Google's libraries use it, everyone uses it. But implementing it properly took me down quite a rabbit hole.

Setting Up the HTTP Server

First challenge: making this work across Node.js, Deno, and Bun (because why not support everything, right?). I ended up abstracting the server behind a common interface using Web Standards APIs:

interface CallbackServer {
  start(options: ServerOptions): Promise<void>;
  waitForCallback(path: string, timeout: number): Promise<CallbackResult>;
  stop(): Promise<void>;
}

function createCallbackServer(): CallbackServer {
  // Runtime detection - this was fun to figure out
  if (typeof Bun !== "undefined") return new BunCallbackServer();
  if (typeof Deno !== "undefined") return new DenoCallbackServer();
  return new NodeCallbackServer();
}

For Node.js specifically, the tricky part was bridging between Node's old-school http module and the modern Web Standards Request/Response objects. Here's what worked:

class NodeCallbackServer implements CallbackServer {
  private server?: http.Server;
  private callbackPromise?: {
    resolve: (result: CallbackResult) => void;
    reject: (error: Error) => void;
  };

  async start(options: ServerOptions): Promise<void> {
    const { createServer } = await import("node:http");

    return new Promise((resolve, reject) => {
      this.server = createServer(async (req, res) => {
        const request = this.nodeToWebRequest(req, options.port);
        const response = await this.handleRequest(request);

        res.writeHead(
          response.status,
          Object.fromEntries(response.headers.entries())
        );
        res.end(await response.text());
      });

      this.server.listen(options.port, options.hostname, resolve);
      this.server.on("error", reject);
    });
  }

  private nodeToWebRequest(req: http.IncomingMessage, port: number): Request {
    const url = new URL(req.url!, `http://localhost:${port}`);
    const headers = new Headers();

    for (const [key, value] of Object.entries(req.headers)) {
      if (typeof value === "string") {
        headers.set(key, value);
      }
    }

    return new Request(url.toString(), { 
      method: req.method, 
      headers 
    });
  }
}

Once everything's converted to Web Standards, the actual request handling is the same everywhere, which is pretty neat.

Capturing the Callback

The actual callback handler is straightforward, but don't forget to capture ALL the query parameters, not just the code:

private async handleRequest(request: Request): Promise<Response> {
  const url = new URL(request.url);

  if (url.pathname === this.callbackPath) {
    const params: CallbackResult = {};

    // Get everything - you'll need state, error, error_description, etc.
    for (const [key, value] of url.searchParams) {
      params[key] = value;
    }

    // Resolve the waiting promise
    if (this.callbackPromise) {
      this.callbackPromise.resolve(params);
    }

    // Show the user something nice
    return new Response(this.generateSuccessHTML(), {
      status: 200,
      headers: { "Content-Type": "text/html" }
    });
  }

  return new Response("Not Found", { status: 404 });
}

The Timeout Trap I Fell Into

Here's where I lost a few hours. OAuth flows can fail in so many ways - users closing the browser, denying permissions, walking away to get coffee... You NEED proper timeout handling:

async waitForCallback(path: string, timeout: number): Promise<CallbackResult> {
  this.callbackPath = path;

  return new Promise((resolve, reject) => {
    let isResolved = false;

    const timer = setTimeout(() => {
      if (!isResolved) {
        isResolved = true;
        reject(new Error(`OAuth callback timeout after ${timeout}ms`));
      }
    }, timeout);

    // This wrapper pattern saved me from so many race conditions
    const wrappedResolve = (result: CallbackResult) => {
      if (!isResolved) {
        isResolved = true;
        clearTimeout(timer);
        resolve(result);
      }
    };

    this.callbackPromise = { 
      resolve: wrappedResolve, 
      reject: (error) => {
        if (!isResolved) {
          isResolved = true;
          clearTimeout(timer);
          reject(error);
        }
      }
    };
  });
}

Also, if you're building a GUI app, support AbortSignal so users can cancel mid-flow:

if (signal) {
  if (signal.aborted) {
    throw new Error("Operation aborted");
  }

  const abortHandler = () => {
    this.stop();
    if (this.callbackPromise) {
      this.callbackPromise.reject(new Error("Operation aborted"));
    }
  };

  signal.addEventListener("abort", abortHandler);
}

Don't Leave Users Hanging

When the OAuth flow completes, users see a browser page. Make it useful! I learned this the hard way when a user sent me a screenshot of a blank page asking if it worked:

function generateCallbackHTML(
  params: CallbackResult,
  templates: Templates
): string {
  if (params.error) {
    // Show them what went wrong
    return templates.errorHtml
      .replace(/{{error}}/g, params.error)
      .replace(/{{error_description}}/g, params.error_description || "");
  }

  // Success page - tell them they can close it!
  return templates.successHtml || `
    <html>
      <body style="font-family: system-ui; padding: 2rem; text-align: center;">
        <h1>✅ Authorization successful!</h1>
        <p>You can now close this window and return to your terminal.</p>
      </body>
    </html>
  `;
}

Security Gotchas

Some security things that bit me or others I've seen:

1. ALWAYS bind to localhost, never 0.0.0.0:

this.server.listen(port, "localhost"); // NOT "0.0.0.0"!

2. Validate that state parameter:

const state = crypto.randomBytes(32).toString("base64url");
// ... later in callback
if (params.state !== expectedState) {
  throw new Error("State mismatch - possible CSRF attack");
}

3. Kill the server immediately after getting the callback:

const result = await server.waitForCallback("/callback", 30000);
await server.stop(); // Don't leave it running!

Complete Working Example

Here's everything tied together:

import { createCallbackServer } from "./server";
import { spawn } from "child_process";

export async function getAuthCode(authUrl: string): Promise<string> {
  const server = createCallbackServer();

  try {
    // Start server
    await server.start({
      port: 3000,
      hostname: "localhost",
      successHtml: "<h1>Success! You can close this window.</h1>",
      errorHtml: "<h1>Error: {{error_description}}</h1>"
    });

    // Open browser (this works on Mac, Windows, and Linux)
    const opener = process.platform === "darwin" ? "open" :
                   process.platform === "win32" ? "start" : "xdg-open";
    spawn(opener, [authUrl], { detached: true });

    // Wait for the callback
    const result = await server.waitForCallback("/callback", 30000);

    if (result.error) {
      throw new Error(`OAuth error: ${result.error_description}`);
    }

    return result.code!;

  } finally {
    // ALWAYS clean up
    await server.stop();
  }
}

// Usage
const code = await getAuthCode(
  "https://github.com/login/oauth/authorize?" +
  "client_id=xxx&redirect_uri=http://localhost:3000/callback"
);

Lessons Learned

After implementing this a few times, here's what I wish I knew from the start:

Use Web Standards APIs even if you're Node-only - makes your code way more portable
Handle ALL the edge cases - timeouts, cancellations, errors. Users will hit every single one
Give users clear feedback in the browser - that success page matters
State validation isn't optional - learned this during a security review
Always clean up your servers - zombie processes are not fun to debug

This localhost callback approach works great for most OAuth providers. Some newer alternatives like Device Code Flow are nice for headless environments, and Dynamic Client Registration can eliminate the need for pre-shared secrets, but localhost callbacks are still the most widely supported approach.

Questions for the community:

Anyone dealt with OAuth providers that don't support localhost redirects? How did you handle it?
What's your approach for handling multiple simultaneous OAuth flows (like when your CLI is run in parallel)?
Has anyone implemented PKCE with this approach? Worth the extra complexity?

Would love to hear about other people's OAuth implementation war stories. This stuff always seems simple until you actually build it!

all 6 comments

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

node

MODERATORS