Skip to main content
Version: 🚧 Canary

🛣️ OAuth Route Blocks

OAuth route blocks provide pre-configured HTTP endpoints for third-party OAuth flows in NodeBlocks applications. These routes compose blocks, logging, and error handling to deliver a robust OAuth experience. Providers currently supported: Google and Twitter.

🎯 Overview​

OAuth route blocks are designed to:

  • Expose OAuth endpoints for initiation and callback processing
  • Compose handlers with logging for observability
  • Centralize error handling with consistent HTTP status mapping
  • Leverage schema validation for query parameters

📋 Route Structure​

Each OAuth route follows a consistent pattern:

  • HTTP Method: Operation type (GET)
  • Path: Endpoint URL
  • Blocks: Composed function chain for OAuth flow orchestration
  • Validators: Authentication and authorization checks (none for OAuth routes)

🔧 Available OAuth Routes​

googleOAuthRoute​

Initiates Google OAuth authentication flow via GET /auth/oauth/google.

Purpose: Starts the Google OAuth flow by delegating to the OAuth driver and preparing state.

Route Details:

  • Method: GET
  • Path: /auth/oauth/google
  • Authentication: Not required

Blocks:

Validators: None (validation handled by schema)

Usage:

import { compose } from '@nodeblocks/backend-sdk';

// Use in feature composition:
export const googleOAuthFeature = compose(googleOauthSchema, googleOAuthRoute);

googleOAuthCallbackRoute​

Processes Google OAuth callback and redirects the user via GET /auth/oauth/google/callback.

Purpose: Completes the OAuth flow by authenticating the provider callback, verifying login state, issuing tokens, and redirecting the user.

Route Details:

  • Method: GET
  • Path: /auth/oauth/google/callback
  • Authentication: Not required

Blocks:

Validators: None (validation handled by schema)

Usage:

import { compose } from '@nodeblocks/backend-sdk';

// Use in feature composition:
export const googleOAuthCallbackFeature = compose(
  googleOAuthCallbackRoute
);

twitterOAuthRoute​

Initiates Twitter OAuth authentication flow via GET /auth/oauth/twitter.

Purpose: Starts the Twitter OAuth flow by delegating to the OAuth driver with prepared state.

Route Details:

  • Method: GET
  • Path: /auth/oauth/twitter
  • Authentication: Not required

Blocks:

  • prepareTwitterCallbackState — Builds { purpose, redirectUrl, typeId }
  • requestTwitterOAuth — Calls driver to start auth

Validators: None (validation handled by schema)

Usage:

import { compose } from '@nodeblocks/backend-sdk';

export const twitterOAuthFeature = compose(twitterOauthSchema, twitterOAuthRoute);

twitterOAuthCallbackRoute​

Processes Twitter OAuth callback and redirects the user via GET /auth/oauth/twitter/callback.

Purpose: Completes the OAuth flow by authenticating the provider callback, verifying user, issuing tokens, and redirecting the user.

Route Details:

  • Method: GET
  • Path: /auth/oauth/twitter/callback
  • Authentication: Not required

Blocks:

  • authenticateTwitterOAuth — Validates provider callback and reads user
  • verifyTwitterOAuth — Resolves or creates identity based on provider profile
  • generateRedirectURL — Generates signed redirect URL with token
  • redirectTo — Issues HTTP redirect to the client

Validators: None (validation handled by schema)

Usage:

import { compose } from '@nodeblocks/backend-sdk';

export const twitterOAuthCallbackFeature = compose(
  twitterOAuthCallbackRoute
);