🛣️ 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:

• requestGoogleOAuth - Initiates Google OAuth flow and generates signed state

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:

• authenticateGoogleOAuth - Validates provider callback and reads user profile
• extractOAuthLoginState - Extracts and validates OAuth login state from encrypted token
• verifyGoogleOAuth - 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';

// 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
);

---