🛣️ OAuth Routes

OAuth routes 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, Twitter, and LINE.

---

🎯 Overview

OAuth routes 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

Handles Google OAuth callback via GET /auth/oauth/google/callback.

Purpose: Processes the OAuth callback, authenticates the user, generates one-time tokens, and redirects to the client application.

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
• checkEmailIsUniqueInIdentities - Validates email uniqueness (signup only)
• verifyGoogleOAuth - Resolves or creates identity based on provider profile
• getLoginTokenTarget - Returns login token target constant
• getFingerprint - Extracts security fingerprint from request
• buildTokenVerification - Builds security context for token generation
• buildJwtOptions - Creates JWT options with expiration
• generateOneTimeToken - Generates one-time authentication token
• storeOneTimeToken - Stores one-time token in database
• generateRedirectURL - Generates redirect URL with onetime 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

Handles Twitter OAuth callback via GET /auth/oauth/twitter/callback.

Purpose: Processes the OAuth callback, authenticates the user, generates one-time tokens, and redirects to the client application.

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
• getLoginTokenTarget - Returns login token target constant
• getFingerprint - Extracts security fingerprint from request
• buildTokenVerification - Builds security context for token generation
• buildJwtOptions - Creates JWT options with expiration
• generateOneTimeToken - Generates one-time authentication token
• storeOneTimeToken - Stores one-time token in database
• generateRedirectURL - Generates redirect URL with onetime 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
);

---

lineOAuthRoute

Initiates LINE OAuth authentication flow via GET /auth/oauth/line.

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

Route Details:

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

Blocks:

• requestLineOAuth - Initiates LINE OAuth flow and generates signed state token

Validators: None (validation handled by schema)

Query Parameters:

• fp: string (required) — Device fingerprint identifier
• purpose: 'oauth-login' | 'oauth-signup' (required) — OAuth flow purpose
• redirectUrl: string (required) — Client redirect destination
• typeId: string (required) — Identity type identifier for signup

Response: Redirects to LINE OAuth authorization page (302)

Handler Process:

1. Receives OAuth initiation request with query parameters
2. Generates one-time token for state management
3. Delegates to LINE OAuth driver to perform redirect
4. User is redirected to LINE authorization page

Usage:

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

// Use in feature composition:
export const lineOAuthFeature = compose(lineOauthSchema, lineOAuthRoute);

Example Request:

GET /auth/oauth/line?fp=1234567890&purpose=oauth-login&redirectUrl=https://app.com/callback&typeId=regular

---

lineOAuthCallbackRoute

Handles LINE OAuth callback via GET /auth/oauth/line/callback.

Purpose: Processes the OAuth callback, authenticates the user, generates one-time tokens, and redirects to the client application.

Route Details:

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

Blocks:

• authenticateLineOAuth - Validates provider callback and reads user profile
• extractOAuthLoginState - Extracts and validates OAuth login state from encrypted token
• verifyLineOAuth - Resolves or creates identity based on provider profile
• getLoginTokenTarget - Returns login token target constant
• getFingerprint - Extracts security fingerprint from request
• buildTokenVerification - Builds security context for token generation
• buildJwtOptions - Creates JWT options with expiration
• generateOneTimeToken - Generates one-time authentication token
• storeOneTimeToken - Stores one-time token in database
• generateRedirectURL - Generates redirect URL with onetime token
• redirectTo - Issues HTTP redirect to the client

Validators: None (validation handled by schema)

Error Responses:

• 400 - AuthenticationInvalidInputError (missing required fields or invalid input)
• 404 - AuthenticationNotFoundError (identity not found for login flow)
• 500 - AuthenticationUnexpectedDBError (database errors), AuthenticationOAuthError (OAuth failures)

Handler Process:

1. Receives callback from LINE with authorization code and state
2. Authenticates user with LINE OAuth driver
3. Extracts and verifies login state from encrypted token
4. Finds existing identity or creates new one (for signup flows)
5. Generates one-time token with security context
6. Stores token in database for verification
7. Redirects user back to client application with token

Usage:

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

// Use in feature composition:
export const lineOAuthCallbackFeature = compose(
  lineOAuthCallbackRoute
);

Example Flow:

1. LINE redirects to: GET /auth/oauth/line/callback?code=ABC123&state=XYZ789
2. Backend processes authentication
3. Backend redirects to: https://app.com/callback?token=JWT_TOKEN

---