dev-oauth

A lightweight, extensible OAuth 2.0 client for Node.js. Currently supports Google OAuth with a plug-and-play architecture for adding more providers. Includes a browser popup utility for seamless OAuth flows.

Installation

npm install dev-oauth

Quick Start

const { createOAuthClient } = require('dev-oauth');

// 1. Initialize the client
const oauth = createOAuthClient({
  google: {
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    redirectUri: 'http://localhost:3000/callback',
  },
});

// 2. Generate the authorization URL and redirect the user
const authUrl = oauth.google.getAuthUrl();
// → https://accounts.google.com/o/oauth2/v2/auth?client_id=...&scope=profile+email&...

// 3. After the user authorizes, exchange the code for tokens
const tokens = await oauth.google.getToken(req.query.code);
console.log(tokens.access_token);

Express Example

A minimal Express server showing the full OAuth flow:

const express = require('express');
const { createOAuthClient } = require('dev-oauth');

const app = express();

const oauth = createOAuthClient({
  google: {
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    redirectUri: 'http://localhost:3000/callback',
  },
});

// Redirect user to Google's consent screen
app.get('/auth/google', (req, res) => {
  const url = oauth.google.getAuthUrl({
    scope: 'openid profile email',
    state: 'some-csrf-token',
  });
  res.redirect(url);
});

// Handle the callback
app.get('/callback', async (req, res) => {
  try {
    const tokens = await oauth.google.getToken(req.query.code);
    res.json(tokens);
  } catch (err) {
    res.status(400).json({ error: err.message });
  }
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));

API

createOAuthClient(config)

Creates an OAuth client with one or more providers.

const oauth = createOAuthClient({
  google: { clientId, clientSecret, redirectUri },
});

Each provider key in the config maps to a provider instance on the returned object. Unsupported keys are silently ignored.

Throws "Configuration object is required" if config is not a plain object.

Provider Config

Every provider requires these three fields:

| Field | Type | Description | |----------------|----------|--------------------------------------| | clientId | string | Your OAuth app's client ID | | clientSecret | string | Your OAuth app's client secret | | redirectUri | string | Callback URL after user authorizes |

Missing any of these throws: "{field} is required for {provider} provider"

provider.getAuthUrl(options?)

Generates the OAuth authorization URL.

| Option | Type | Default | Description | |----------|----------|--------------------|---------------------------------| | scope | string | "profile email" | Space-separated OAuth scopes | | state | string | — | CSRF protection token |

Returns a string.

// Defaults
oauth.google.getAuthUrl();

// Custom scopes + state
oauth.google.getAuthUrl({
  scope: 'openid profile email https://www.googleapis.com/auth/calendar.readonly',
  state: crypto.randomUUID(),
});

provider.getToken(code)

Exchanges an authorization code for access tokens.

| Param | Type | Description | |--------|----------|------------------------------------------| | code | string | The authorization code from the callback |

Returns a Promise resolving to:

| Field | Type | Description | |-----------------|----------|------------------------------------------------| | access_token | string | The OAuth access token | | token_type | string | Typically "Bearer" | | expires_in | number | Seconds until the token expires | | refresh_token | string | Present if offline access was requested | | scope | string | The scopes that were granted | | id_token | string | JWT ID token (when openid scope is included) |

Throws "Authorization code is required" if code is missing or empty.

try {
  const tokens = await oauth.google.getToken(code);
  console.log(tokens.access_token);
} catch (err) {
  console.error('Token exchange failed:', err.message);
}

Popup OAuth (Browser)

Open the OAuth consent screen in a popup instead of redirecting the whole page:

// In your React/frontend code
import { openOAuthPopup } from 'dev-oauth/src/browser/popup';

async function handleLogin() {
  try {
    // Opens popup → user logs in → popup closes → returns URL params
    const result = await openOAuthPopup('/auth/google');
    console.log(result); // { token: '...', ... } or { code: '...' }
  } catch (err) {
    console.error(err.message); // "Popup was blocked" or "Popup was closed"
  }
}

Your backend callback route should redirect to a page on your origin with the result as query params. The popup utility detects when the popup returns to your origin, reads the params, and closes the popup automatically.

Options:

| Option | Type | Default | Description | |----------------|----------|------------------|--------------------------------| | width | number | 500 | Popup width in pixels | | height | number | 600 | Popup height in pixels | | name | string | "oauth-popup" | Window name | | pollInterval | number | 500 | Check interval in ms |

Error Handling

The package throws standard Error instances with clear messages:

// Missing config
createOAuthClient(null);
// → Error: "Configuration object is required"

// Missing provider field
createOAuthClient({ google: { clientId: '...' } });
// → Error: "clientSecret is required for google provider"

// Missing authorization code
await oauth.google.getToken('');
// → Error: "Authorization code is required"

// Failed token exchange (network/API error)
await oauth.google.getToken('invalid-code');
// → Error: contains the error details from Google's response

Adding Providers

The architecture supports adding new providers without touching existing code. To add GitHub, for example:

1. Create src/providers/github.js with a factory that returns { getAuthUrl, getToken }
2. Register it in src/core/client.js:

const providers = {
  google: createGoogleProvider,
  github: createGithubProvider, // new
};

Then use it:

const oauth = createOAuthClient({
  google: { ... },
  github: { clientId, clientSecret, redirectUri },
});

oauth.github.getAuthUrl();

Requirements

• Node.js 14+
• An OAuth application registered with your provider (e.g., Google Cloud Console)

License

MIT