🔍 OAuth Schemas

OAuth schemas provide OpenAPI-compatible schema and parameter definitions used to validate and document OAuth-related endpoints. Providers currently supported: Google, Twitter, and LINE.

---

🎯 Overview

OAuth schemas are designed to:

• Validate OAuth request data consistently across providers
• Ensure security with explicit query parameter contracts
• Provide clear API contracts for initiation and callback endpoints
• Enable type safety with TypeScript integration
• Support composition with NodeBlocks features and routes

---

📋 OAuth Schema Types

Base Parameter Schemas

Reusable OpenAPI parameters for OAuth flows.

OAuth Initiation Schemas

Schemas for starting the OAuth authorization process.

---

🔧 Available OAuth Schemas

fpQueryParameter

Fingerprint query parameter for Google OAuth request tracking and security validation.

Purpose: Correlates the OAuth flow to a specific device/browser via fingerprinting.

Parameter Details:

• Location: query
• Name: fp
• Required: true
• Schema: { type: 'string' }

Usage:

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

const { fpQueryParameter } = schemas;

export const googleOauthSchema = withSchema({
  parameters: [fpQueryParameter]
});

---

purposeQueryParameter

Purpose query parameter for Google OAuth flow type specification (login/signup).

Purpose: Declares the intent of the OAuth flow to direct backend behavior.

Parameter Details:

• Location: query
• Name: purpose
• Required: true
• Schema: { type: 'string', enum: ['oauth-login', 'oauth-signup'] }

Usage:

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

const { purposeQueryParameter } = schemas;

export const googleOauthSchema = withSchema({
  parameters: [purposeQueryParameter]
});

---

redirectUrlQueryParameter

Redirect URL query parameter for Google OAuth callback destination specification.

Purpose: Instructs the system where to redirect the user-agent after the OAuth flow completes.

Parameter Details:

• Location: query
• Name: redirectUrl
• Required: true
• Schema: { type: 'string' }

Usage:

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

const { redirectUrlQueryParameter } = schemas;

export const googleOauthSchema = withSchema({
  parameters: [redirectUrlQueryParameter]
});

---

typeIdQueryParameter

Type ID query parameter for Google OAuth flow identification and routing.

Purpose: Optionally tags the identity type for the user being created or logged in (e.g., admin, user).

Parameter Details:

• Location: query
• Name: typeId
• Required: false
• Schema: { type: 'string' }

Usage:

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

const { typeIdQueryParameter } = schemas;

export const googleOauthSchema = withSchema({
  parameters: [typeIdQueryParameter]
});

---

stateQueryParameter

State query parameter for Google OAuth callback verification and security validation.

Purpose: Used for Google OAuth callback verification and security validation.

Parameter Details:

• Location: query
• Name: state
• Required: true
• Schema: { type: 'string' }

Usage:

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

const { stateQueryParameter } = schemas;

export const googleOAuthCallbackSchema = withSchema({
  parameters: [stateQueryParameter]
});

---

googleOauthSchema

Google OAuth initiation schema with query parameters and empty request body validation.

Purpose: Validates the input for starting the Google OAuth flow.

Schema Details:

• Parameters: fp, purpose, redirectUrl, typeId
• Request Body:
  • Content-Type: application/json
  • Schema: { type: 'object', maxProperties: 0 } (no payload allowed)

Usage:

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

const { googleOauthSchema } = schemas;

export const googleOAuthFeature = compose(googleOauthSchema, googleOAuthRoute);

---

twitterOauthSchema

Twitter OAuth initiation schema with query parameters and empty request body validation.

Purpose: Validates the input for starting the Twitter OAuth flow.

Schema Details:

• Parameters: purpose, redirectUrl, typeId
• Request Body:
  • Content-Type: application/json
  • Schema: { type: 'object', maxProperties: 0 } (no payload allowed)

Usage:

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

const { twitterOauthSchema } = schemas;

export const twitterOAuthFeature = compose(twitterOauthSchema, twitterOAuthRoute);

---

lineOauthSchema

LINE OAuth initiation schema with query parameters and empty request body validation.

Purpose: Validates the input for starting the LINE OAuth flow.

Schema Details:

• Parameters: fp, purpose, redirectUrl, typeId
• Request Body:
  • Content-Type: application/json
  • Schema: { type: 'object', maxProperties: 0 } (no payload allowed)

Query Parameters:

• fp: string (required) — Fingerprint identifier for device/browser tracking
• purpose: 'oauth-login' | 'oauth-signup' (required) — OAuth flow purpose
• redirectUrl: string (required) — Client redirect destination after completion
• typeId: string (required) — Identity type identifier for signup flows

Usage:

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

const { lineOauthSchema } = schemas;

export const lineOAuthFeature = compose(lineOauthSchema, lineOAuthRoute);

Example Request:

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

Key Features:

• Validates all required query parameters
• Enforces empty request body (maxProperties: 0)
• Used with LINE OAuth initiation route
• Supports both login and signup flows

---