メインコンテンツまでスキップ
バージョン: 🚧 Canary

🔍 OAuth Schema Blocks

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

🎯 Overview​

OAuth schema blocks 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);