メインコンテンツまでスキップ
バージョン: 0.5.0 (最新)

🔐 認証ルートブロック

認証ルートブロックは、NodeBlocks アプリケーションにおけるユーザー認証および認可操作のための事前設定された HTTP エンドポイントを提供します。これらのルートは、ブロック（純粋なビジネスロジック関数）、ハンドラー、バリデーター、およびミドルウェアを組み合わせ、ログイン、登録、トークン管理、メール認証のための完全な API エンドポイントを作成します。

🎯 概要​

認証ルートブロックは次のことを目的として設計されています:

  • ユーザー認証操作のための完全な API エンドポイントを提供する
  • ブロックとハンドラーをバリデーターと組み合わせ、安全な操作を実現する
  • 認証および認可チェックを含む
  • 関数型合成パターンをサポートする
  • ログ記録とエラー管理を自動的に処理する

📋 ルート構造​

各認証ルートは一貫したパターンを従います:

  • HTTP メソッド: 操作タイプを定義（GET、POST、PATCH、DELETE）
  • パス: パラメータを含むエンドポイント URL を指定
  • ハンドラー: ブロックとハンドラーを使用した合成関数チェーン
  • バリデーター: 認証および認可チェック

🔧 利用可能な認証ルート​

registerCredentialsRoute​

オプションの招待処理を使用して新規ユーザー資格情報を登録します。

目的: 招待受付のサポートを使用してユーザー登録を処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/register
  • 認証: 不要

ハンドラー:

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.registerCredentialsRoute);

注記: 招待固有の機能については、招待ブロック を参照してください。

loginWithCredentialsRoute​

ユーザー資格情報を認証し、アクセス/リフレッシュトークンを生成します。

目的: 資格情報検証を使用したユーザーログインを処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/login
  • 認証: 不要

ハンドラー: loginWithCredentials, createAccessToken, createRefreshToken, setResponseCookie, loginTerminator

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.loginWithCredentialsRoute);

logoutRoute​

セッションを無効化しトークンをクリアすることでユーザーをログアウトします。

目的: ユーザーログアウトとセッションクリーンアップを処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/logout
  • 認証: 必須（Bearer トークン）

ハンドラー: logout, logoutTerminator

バリデーター: isAuthenticated

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.logoutRoute);

refreshTokenRoute​

有効なリフレッシュトークンを使用してアクセストークンを更新します。

目的: リフレッシュトークンから新しいアクセストークンを生成します

ルート詳細:

  • メソッド: POST
  • パス: /auth/token/refresh
  • 認証: 必須（Bearer トークン）

ハンドラー: refreshToken

バリデーター: isAuthenticated

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.refreshTokenRoute);

checkTokenRoute​

アクセストークンを検証し、そのステータスを返します。

目的: トークンの正当性とステータスを検証します

ルート詳細:

  • メソッド: POST
  • パス: /auth/token/check
  • 認証: 不要

ブロック: checkToken - 純粋なビジネスロジックを使用してトークンを検証

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.checkTokenRoute);

deleteTokenRoute​

システムから認証トークンを削除します。

目的: 認証トークンを削除（管理者のみ）

ルート詳細:

  • メソッド: POST
  • パス: /auth/token/delete
  • 認証: 必須（Bearer トークン）

ハンドラー: deleteToken

バリデーター: isAuthenticated, checkIdentityType(['admin'])

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.deleteTokenRoute);

loginWithOnetimeTokenRoute​

ワンタイムトークンを使用してユーザーを認証し、アクセス資格情報を返します。

目的: OTT ベースの認証を処理します

ルート詳細:

  • メソッド: GET
  • パス: /auth/ott/login
  • 認証: 不要

ハンドラー: loginWithOnetimeToken

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.loginWithOnetimeTokenRoute);

generateOnetimeTokenRoute​

認証目的で新しいワンタイムトークンを生成します。

目的: 認証用の OTT を作成（管理者のみ）

ルート詳細:

  • メソッド: POST
  • パス: /auth/ott/generate
  • 認証: 必須（Bearer トークン）

ハンドラー: generateOnetimeToken

バリデーター: isAuthenticated, checkIdentityType(['admin'])

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.generateOnetimeTokenRoute);

restoreOnetimeTokenRoute​

以前に無効化されたワンタイムトークンを復元します。

目的: 無効化された OTT を再有効化（管理者のみ）

ルート詳細:

  • メソッド: POST
  • パス: /auth/ott/restore
  • 認証: 必須（Bearer トークン）

ハンドラー: restoreOnetimeToken

バリデーター: isAuthenticated, checkIdentityType(['admin'])

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.restoreOnetimeTokenRoute);

invalidateOnetimeTokenRoute​

既存のワンタイムトークンを無効化します。

目的: アクティブな OTT を無効化（管理者のみ）

ルート詳細:

  • メソッド: POST
  • パス: /auth/ott/invalidate
  • 認証: 必須（Bearer トークン）

ハンドラー: invalidateOnetimeToken

バリデーター: isAuthenticated, checkIdentityType(['admin'])

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.invalidateOnetimeTokenRoute);

sendVerificationEmailRoute​

ユーザーに認証メールを送信します。

目的: メール認証プロセスをトリガーします

ルート詳細:

  • メソッド: POST
  • パス: /auth/:identityId/send-verification-email
  • 認証: 必須（Bearer トークン）

ハンドラー: sendVerificationEmail, sendVerificationEmailTerminator

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.sendVerificationEmailRoute);

confirmEmailRoute​

認証トークンを使用してユーザーのメールアドレスを確認します。

目的: メール認証トークンを処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/confirm-email
  • 認証: 不要

ハンドラー: buildCheckConfirmEmailTokenPayload, checkToken, confirmEmail, confirmEmailTerminator

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.confirmEmailRoute);

changeEmailRoute​

新しいアドレスに認証メールを送信することで、ユーザーのメール変更プロセスを開始します。

目的: トークン生成とメール送信を使用したメール変更開始を処理します

ルート詳細:

  • メソッド: PATCH
  • パス: /auth/:identityId/change-email
  • 認証: 必須（Bearer トークン）

ブロック:

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.changeEmailRoute);

confirmNewEmailRoute​

ワンタイム認証トークンを使用してユーザーの新しいメールアドレスを確認します。

目的: トークン検証を使用したメール変更確認を処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/confirm-new-email
  • 認証: 不要

ブロック:

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.confirmNewEmailRoute);

sendResetPasswordLinkEmailRoute​

ユーザーのメールアドレスに基づいて、パスワードリセットリンクメールを送信します。

目的: パスワードリセットメールの生成と送信を処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/send-reset-password-link-email
  • 認証: 不要

ブロック:

バリデーター: なし

使用例:

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

// Express アプリにルートを登録
app.use('/api', routes.sendResetPasswordLinkEmailRoute);

changePasswordRoute​

PATCH /auth/:identityId/change-password を介してユーザーパスワードを変更します。

目的: 現在のパスワード検証と新しいパスワードのハッシュ化を使用したパスワード変更を処理します

ルート詳細:

  • メソッド: PATCH
  • パス: /auth/:identityId/change-password
  • 認証: 必須（Bearer トークン）

ブロック:

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestParams', 'identityId']))

使用例:

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

// 機能合成で使用:
export const changePasswordFeature = compose(changePasswordSchema, changePasswordRoute);

// Express アプリにルートを登録
app.use('/api', routes.changePasswordRoute);

activateRoute​

POST /auth/activate を介してユーザーアカウントを有効化します。

目的: メール認証とアイデンティティステータス更新を使用したアカウント有効化を処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/activate
  • 認証: 必須（Bearer トークン）

ブロック:

バリデーター: isAuthenticated, checkIdentityType(['admin'])

使用例:

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

// 機能合成で使用:
export const activateFeature = compose(activateSchema, activateRoute);

// Express アプリにルートを登録
app.use('/api', routes.activateRoute);

deactivateRoute​

POST /auth/deactivate を介してユーザーアイデンティティを無効化します。

目的: メール認証、アイデンティティステータス更新、トークン無効化を使用したアカウント無効化を処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/deactivate
  • 認証: 必須（Bearer トークン）

ブロック:

バリデーター: isAuthenticated, some(checkIdentityType(['admin']), isSelf(['params', 'requestBody', 'identityId']))

使用例:

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

// 機能合成で使用:
export const deactivateFeature = compose(deactivateSchema, routes.deactivateRoute);

// Express アプリにルートを登録
app.use('/api', routes.deactivateRoute);

completePasswordResetRoute​

トークンの検証とユーザーパスワードの更新により、パスワードリセットプロセスを完了します。

目的: トークン検証とパスワード更新を使用したパスワードリセット完了を処理します

ルート詳細:

  • メソッド: POST
  • パス: /auth/reset-password
  • 認証: 不要

ブロック:

バリデーター: なし

使用例:

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

// ルート登録:
app.use('/api', routes.completePasswordResetRoute);

// POST /auth/reset-password
// ヘッダー:
//   Authorization: Bearer <one-time-token>
// リクエストボディ:
// {
//   "password": "newStrongPassword123"
// }
// レスポンス: 204 No Content (success)