🔐 OAuth Drivers

OAuth drivers provide a consistent integration layer for third-party OAuth providers using Passport.js. They encapsulate provider strategy setup and expose simple request and callback helpers you can compose into routes and features.

---

🎯 Overview

OAuth drivers in NodeBlocks are thin wrappers around Passport.js strategies that provide:

• Strategy setup with provider credentials and scopes
• Promise-based request/callback helpers for composition
• Pluggable verification callbacks to normalize provider profiles

---

📋 Available OAuth Drivers

Google OAuth Driver

The Google OAuth driver integrates Passport.js Google strategy and exposes helpers for request and callback handling.

verifyGoogleCallback

Verifies Google OAuth callback and processes user profile data for Google Passport.js authentication.

Parameters:

• _req: Request — Express request object (unused in this implementation)
• accessToken: string — Google OAuth access token for API access
• refreshToken: string — Google OAuth refresh token for token renewal
• profile: Profile — Google user profile data from OAuth callback
• done: VerifyCallback — Passport.js verification callback function

Returns: void — Calls done callback with result or error

Handler Process:

• Input: Express request, access token, refresh token, Google profile, and verification callback
• Process: Extracts email from profile, validates email presence, formats profile data for authentication
• Output: Calls done callback with formatted profile data or error
• Errors: AuthenticationBadRequestError when email is missing from Google profile

Usage:

passport.use(new GoogleStrategy({
  verify: verifyGoogleCallback
}));

createGoogleOAuthDriver

Creates Google OAuth driver with Passport.js strategy and authentication handlers.

Parameters:

• clientID: string — Google OAuth client ID from Google Cloud Console
• clientSecret: string — Google OAuth client secret from Google Cloud Console
• callbackURL: string — URL where Google will redirect after OAuth completion
• scope: string[] — Array of OAuth scopes to request (defaults to ['email', 'profile'])
• verify: typeof verifyGoogleCallback — Optional verification function (defaults to verifyGoogleCallback)

Returns: GoogleOAuthDriver — GoogleOAuthDriver object with complete OAuth flow management

Handler Process:

• Input: Google OAuth credentials (clientID, clientSecret), callback URL, scope, and optional verification function
• Process: Configures Passport.js Google strategy, creates callback and request handlers with Promise wrappers
• Output: GoogleOAuthDriver object with callback, initialize, and request functions
• Errors: Errors from Passport.js authentication or Promise rejections

Usage:

// Create Google OAuth driver:
const googleDriver = createGoogleOAuthDriver(
  'your-client-id',
  'your-client-secret',
  'https://app.com/auth/google/callback'
);

// Use in Express app:
app.use('/auth/google', googleDriver.initialize);

Twitter OAuth Driver

The Twitter OAuth driver integrates Passport.js Twitter strategy and exposes helpers for request and callback handling with session management.

verifyTwitterCallback

Verifies the Twitter OAuth callback and extracts user information.

Parameters:

• _req: Request — Express request object (unused)
• accessToken: string — OAuth access token (unused)
• refreshToken: string — OAuth refresh token (unused)
• profile: TwitterUserInfoPayload — Twitter user profile information
• done: VerifyCallback — Callback function to signal completion

Returns: void — Calls done callback with result or error

Handler Process:

• Input: Receives OAuth tokens and Twitter user profile
• Process: Validates the presence of profile, id, and username
• Output: Returns user information including displayName, id, and username
• Errors: Returns AuthenticationOAuthError if profile, id, or username is missing

Usage:

passport.use(new TwitterStrategy({
  clientID: TWITTER_CLIENT_ID,
  clientSecret: TWITTER_CLIENT_SECRET,
  callbackURL: "http://www.example.com/auth/twitter/callback"
}, verifyTwitterCallback));

createTwitterOAuthDriver

Creates a Twitter OAuth driver for handling authentication flows.

Parameters:

• clientID: string — The client ID for the Twitter application
• clientSecret: string — The client secret for the Twitter application
• callbackURL: string — The callback URL for Twitter OAuth
• sessionSecret: string — The secret for session management
• verify: VerifyFunctionWithRequest — Optional verification function for handling Twitter OAuth callbacks

Returns: TwitterOAuthDriver — TwitterOAuthDriver object with complete OAuth flow management

Handler Process:

• Input: Accepts clientID, clientSecret, callbackURL, sessionSecret, and an optional verify function
• Process: Configures the Twitter strategy with Passport and sets up session middleware
• Output: Returns a TwitterOAuthDriver with methods for callback, initialization, and request handling

Usage:

const twitterDriver = createTwitterOAuthDriver(
  'your-client-id',
  'your-client-secret',
  'https://yourapp.com/auth/twitter/callback',
  'your-session-secret'
);

// Use in Express app:
app.use('/auth/twitter', twitterDriver.initialize);

---

🔗 Related Documentation

• OAuth Blocks — Business logic for OAuth flows
• OAuth Routes — HTTP route compositions for OAuth