バージョン: 0.9.0 (最新)

🚀 認証機能

認証機能は、Nodeblocksアプリケーションでユーザー認証操作のための完全な事前構成済み機能を提供します。これらの機能は、スキーマ、ルート、ハンドラーを組み合わせて、ログイン、登録、メール確認、セッション管理のための即座に使用可能なAPIエンドポイントを作成します。

🎯 概要

認証機能は以下の目的で設計されています：

完全な認証ワークフローの提供 - ユーザーログインと登録のためのワークフロー
スキーマとルートの組み合わせ - バリデーション済み認証操作のための統合
セキュリティ対策とトークン管理の自動実装 - 自動的なセキュリティ機能
メール確認とアカウント確認フローのサポート - 確認フローの対応
シームレスなセッション管理とログアウト操作 - セッション管理の処理

📋 機能構造

各認証機能は一貫したコンポジションパターンに従います：

Schema: 認証入力データとパラメータをバリデーション
Route: 認証ハンドラーを含むHTTPエンドポイントを提供
構成: compose関数を使用してスキーマとルートを組み合わせ

🔧 利用可能な認証機能

`loginWithCredentialsFeature`

認証情報のバリデーションを含む完全なログインとログアウト機能を提供します。

目的: バリデーション済み認証情報と安全なログアウトによるユーザー認証を処理

構成:

Schema: loginWithCredentialsSchema - ログイン認証情報をバリデーション
Routes: loginWithCredentialsRoute - POST /auth/login 認証ハンドラー付き
Routes: logoutRoute - POST /auth/logout セッション終了付き

使用法:

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


// データベース設定付き
app.use('/api/auth', defService(partial(features.loginWithCredentialsFeature, [{ dataStores: db }])));

APIエンドポイント:

POST /api/auth/login - ユーザー認証
POST /api/auth/logout - セッション終了

`verifyMfaCodeFeature`

スキーマバリデーションとルーティングを含むMFAコード確認機能。

目的: ユーザー提供のMFAコードを確認して多要素認証を完了

構成:

Schema: verifyMfaCodeSchema - MFA確認リクエストパラメータをバリデーション
Route: verifyMfaCodeRoute - POST /auth/mfa/verify コード確認ハンドラー付き

使用法:

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

// 直接使用:
app.use('/api', features.verifyMfaCodeFeature);

// データベース設定付き（ハンドラーはdataStoresが必要）:
app.use('/api', defService(partial(features.verifyMfaCodeFeature, [{ dataStores: db }])));

// 完全なMFAフローの例:
import express from 'express';
import { features, middlewares } from '@nodeblocks/backend-sdk';

const app = express()
  .use(express.json())
  .use('/api', features.loginWithCredentialsFeature)  // MFA有効時にMFAトークンを返す
  .use('/api', features.verifyMfaCodeFeature)         // コードを確認して認証トークンを返す
  .use(middlewares.nodeBlocksErrorMiddleware())
  .listen(3000);

APIエンドポイント: POST /api/auth/mfa/verify

リクエストボディ:

{
  "token": "encrypted-mfa-challenge-token",
  "code": "123456"
}

レスポンスボディ（成功時）:

{
  "id": "identity-uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

主な機能:

MFAトークンの有効性と有効期限を確認
ユーザー提供のコードと保存されたコードを比較
使用後にワンタイムMFAトークンを無効化
成功時に標準的な認証トークンを返す
MFA認証ワークフローを完了

エラーレスポンス:

400 Bad Request: 無効なMFAコードが提供された
401 Unauthorized: MFAトークンの有効期限切れまたは無効
404 Not Found: データベースにMFAトークンが見つからない
500 Internal Server Error: 予期しない確認エラー

MFAワークフロー統合:

ユーザーが認証情報でログイン（POST /auth/login）
MFAが有効な場合、サーバーがメールでコードを送信し、MFAトークンを返す
ユーザーがメールでコードを受信
ユーザーがMFAトークンと共にコードを送信（POST /auth/mfa/verify）
サーバーがコードをバリデーションし、アクセス/リフレッシュトークンを返す
クライアントは認証済みリクエストを実行可能

注意事項:

認証サービス設定でisMfaEnabled: trueが必要
MFAトークンはワンタイム使用で自動的に無効化される
MFAが有効な場合、loginWithCredentialsFeatureと連携
一貫性のため、標準ログインと同じトークン構造を返す

`resendMfaCodeFeature`

確認コードの再生成のためのスキーマバリデーションとルーティングを含むMFAコード再送信機能。

目的: 新しい確認コードが必要なユーザー向けの完全なMFAコード再生成ワークフローを提供

構成:

Schema: resendMfaCodeSchema - 再送信リクエスト用のMFAトークンをバリデーション
Route: resendMfaCodeRoute - POST /auth/mfa/resend コード再生成ハンドラー付き

使用法:

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

// 直接使用:
app.use('/api', features.resendMfaCodeFeature);

// データベース設定付き（ハンドラーはdataStoresが必要）:
app.use('/api', defService(partial(features.resendMfaCodeFeature, [{ dataStores: db }])));

// 再送信を含む完全なMFAフローの例:
import express from 'express';
import { features, middlewares } from '@nodeblocks/backend-sdk';

const app = express()
  .use(express.json())
  .use('/api', features.loginWithCredentialsFeature)  // MFA有効時にMFAトークンを返す
  .use('/api', features.resendMfaCodeFeature)         // 新しいMFAコードを再送信
  .use('/api', features.verifyMfaCodeFeature)         // コードを確認して認証トークンを返す
  .use(middlewares.nodeBlocksErrorMiddleware())
  .listen(3000);

APIエンドポイント: POST /api/auth/mfa/resend

リクエストボディ:

{
  "token": "encrypted-mfa-challenge-token"
}

レスポンスボディ（成功時）:

{
  "token": "new-encrypted-mfa-challenge-token"
}

主な機能:

セキュリティのため、以前のMFAトークンを無効化
完全に新しいMFAコードを生成
新しい有効期限で新しいMFAトークンを作成
メールで新しいコードを送信
トークンベースのMFAワークフローを維持
トークンの再利用とリプレイ攻撃を防止

エラーレスポンス:

400 Bad Request: 無効なリクエストボディまたはトークンフォーマット
401 Unauthorized: MFAトークンの有効期限切れまたは無効
403 Forbidden: トークンが既に使用済みまたはターゲットが間違っている
404 Not Found: MFAトークンまたはアイデンティティが見つからない
500 Internal Server Error: 再生成中の予期しないエラー

MFA再送信ワークフロー:

ユーザーが認証情報でログイン（POST /auth/login）
MFAが有効な場合、サーバーがメールでコードを送信し、MFAトークンを返す
ユーザーがメールを受信しないか、コードが期限切れになる
ユーザーが古いトークンと共に新しいコードをリクエスト（POST /auth/mfa/resend）
サーバーが古いトークンを無効化し、新しいコードを生成
サーバーがメールで新しいコードを送信し、新しいトークンを返す
ユーザーがメールで新しいコードを受信
ユーザーが新しいトークンと共に新しいコードを送信（POST /auth/mfa/verify）
サーバーがバリデーションし、アクセス/リフレッシュトークンを返す

使用例:

ユーザーが初期MFAコードメールを受信しなかった
メール配信が遅延または失敗した
ユーザーが誤ってメールを削除した
ユーザーが入力する前にMFAコードが期限切れになった
ユーザーが一時的にメールへのアクセスを失い、再度アクセスを取得した

注意事項:

認証サービス設定でisMfaEnabled: trueが必要
古いMFAトークンは再送信時に即座に無効化される
セキュリティのため、新しいMFAコードは常に古いものと異なる
再送信ごとにトークンの有効期限タイマーがリセットされる
loginWithCredentialsFeatureとverifyMfaCodeFeatureとシームレスに連携
メールテンプレートと送信者はサービスオプションで設定可能

`loginWithOnetimeTokenFeature`

パスワードレス認証のためのスキーマバリデーションとルーティングを含むワンタイムトークンログイン機能。

目的: ワンタイムトークン（マジックリンク）を使用した完全なパスワードレス認証ワークフローを提供

構成:

Schema: loginWithOnetimeTokenSchema - ワンタイム認証トークンをバリデーション
Route: loginWithOnetimeTokenRoute - POST /auth/ott/login トークン認証付き

使用法:

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

// 直接使用:
app.use('/api', features.loginWithOnetimeTokenFeature);

// データベース設定付き（ハンドラーはdataStoresが必要）:
app.use('/api', defService(partial(features.loginWithOnetimeTokenFeature, [{ dataStores: db }])));

// 完全なマジックリンクフローの例:
import express from 'express';
import { features, middlewares } from '@nodeblocks/backend-sdk';

const app = express()
  .use(express.json())
  .use('/api', features.loginWithOnetimeTokenFeature)  // パスワードレスログイン
  .use(middlewares.nodeBlocksErrorMiddleware())
  .listen(3000);

APIエンドポイント: POST /api/auth/ott/login

リクエストボディ:

{
  "token": "encrypted-onetime-authentication-token"
}

レスポンスボディ（成功時）:

{
  "id": "identity-uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

主な機能:

マジックリンクによるパスワードレス認証
ワンタイムトークンのバリデーションと無効化
安全なトークンタイプとターゲットの確認
トークンペイロードからのアイデンティティ検索
標準的な認証トークンを返す
使用後の自動トークン無効化

エラーレスポンス:

403 Forbidden: 無効なトークン、間違ったターゲット、または既に使用済み
404 Not Found: アイデンティティが見つからない
500 Internal Server Error: 予期しない認証エラー

マジックリンクワークフロー:

ユーザーがマジックリンクをリクエスト（別のエンドポイント - この機能には含まれない）
システムがtarget: 'login'とidentityIdでワンタイムトークンを生成
システムがトークンを含むマジックリンクメールを送信
ユーザーがメールを受信し、マジックリンクをクリック
クライアントがトークンと共にPOST /auth/ott/loginを送信
システムがトークンをバリデーションし、アイデンティティを取得
システムがトークンを無効化（ワンタイム使用）
システムがアクセスとリフレッシュトークンを返す
ユーザーが認証される

使用例:

マジックリンクメール認証
パスワードレスログインフロー
安全な一時アクセス
メールベースの認証
モバイルフレンドリーな認証

注意事項:

トークンはtype: 'onetime'とtarget: 'login'を持つ必要がある
トークンはワンタイム使用で、ログイン後に自動的に無効化される
一貫性のため、標準的な認証情報ログインと同じトークン構造を返す
マジックリンクメールを生成して送信するための別のエンドポイント/ロジックが必要

`registerCredentialsFeature`

認証情報のバリデーションとアカウント作成を含むユーザー登録を処理します。

目的: データバリデーションを含む新しいユーザー登録を処理

構成:

Schema: registerCredentialsSchema - 登録データをバリデーション
Route: registerCredentialsRoute - POST /auth/register アカウント作成付き

使用法:

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


// データベース設定付き
app.use('/api/auth', defService(partial(features.registerCredentialsFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/register

`emailVerificationFeature`

アカウント確認のための確認メールをユーザーに送信します。

目的: メール確認リクエスト処理を処理

構成:

Schema: sendVerificationEmailSchema - デバイスセキュリティ用のオプションのフィンガープリントをバリデーション
Route: sendVerificationEmailRoute - POST /auth/:identityId/send-verification-email メール送信付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.emailVerificationFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/:identityId/send-verification-email

`confirmEmailFeature`

ユーザーアカウントを確認するためのメール確認トークンを処理します。

目的: メール確認トークンをバリデーションし、ユーザーアカウントを確認

構成:

Schema: confirmEmailSchema - メールからの確認トークンをバリデーション
Route: confirmEmailRoute - POST /auth/confirm-email トークン処理付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.confirmEmailFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/confirm-email

`changeEmailFeature`

ユーザーのメールアドレスを更新するためのスキーマバリデーションとルーティングを含むメール変更機能。

目的: バリデーションを含むメール変更の開始を処理

構成:

Schema: changeEmailSchema - identityIdと新しいメールをバリデーション（ハンドラー内の内部パスワード確認も含む）
Route: changeEmailRoute - PATCH /auth/:identityId/change-email メール更新処理付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.changeEmailFeature, [{ dataStores: db }])));

APIエンドポイント: PATCH /api/auth/:identityId/change-email

`checkTokenFeature`

認証チェックのためのスキーマバリデーションとルーティングを含むトークンバリデーション機能。

目的: ターゲットコンテキストを含むトークンバリデーションを処理

構成:

Schema: checkTokenSchema - トークンとオプションのターゲットパラメータをバリデーション
Route: checkTokenRoute - POST /auth/token/check トークンバリデーションハンドラー付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.checkTokenFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/token/check

`confirmNewEmailFeature`

新しいメールアドレス確認のためのスキーマバリデーションを含むメール確認機能。

目的: メール変更後の新しいメール確認を処理

構成:

Schema: confirmNewEmailSchema - 新しいメールアドレス用の確認トークンをバリデーション
Route: confirmNewEmailRoute - POST /auth/confirm-new-email 新しいメール確認付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.confirmNewEmailFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/confirm-new-email

`sendResetPasswordLinkEmailFeature`

パスワード回復のためのスキーマバリデーションとルーティングを含むパスワードリセットメール機能。

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

構成:

Schema: sendResetPasswordLinkEmailSchema - パスワードリセット用のメールアドレスをバリデーション
Route: sendResetPasswordLinkEmailRoute - POST /auth/send-reset-password-link-email パスワードリセットメール送信付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.sendResetPasswordLinkEmailFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/send-reset-password-link-email

`changePasswordFeature`

ユーザーパスワードを更新するためのスキーマバリデーションとルーティングを含むパスワード変更機能。

目的: 現在のパスワード確認と新しいパスワードのハッシュ化を含むパスワード変更を処理

構成:

Schema: changePasswordSchema - 現在のパスワードと新しいパスワードをバリデーション
Route: changePasswordRoute - PATCH /auth/:identityId/change-password パスワード更新処理付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.changePasswordFeature, [{ dataStores: db }])));

APIエンドポイント: PATCH /api/auth/:identityId/change-password

`activateFeature`

ユーザーアカウントを有効化するためのスキーマバリデーションとルーティングを含むアカウント有効化機能。

目的: メール確認とアイデンティティステータス更新を含むアカウント有効化を処理

構成:

Schema: activateSchema - アイデンティティ有効化リクエストをバリデーション（identityIdが必要）
Route: activateRoute - POST /auth/activate アカウント有効化処理付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.activateFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/activate

`deactivateFeature`

ユーザーアカウントを無効化するためのスキーマバリデーションとルーティングを含むアカウント無効化機能。

目的: アイデンティティステータス更新とトークン無効化を含むアカウント無効化を処理

構成:

Schema: deactivateSchema - 無効化リクエストをバリデーション
Route: deactivateRoute - POST /auth/deactivate アカウント無効化処理付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.deactivateFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/deactivate

`completePasswordResetFeature`

ユーザーパスワードをリセットするためのスキーマバリデーションとルーティングを含む完全なパスワードリセット機能。

目的: トークンバリデーションとパスワード更新を含むパスワードリセット完了を処理

構成:

Schema: completePasswordResetSchema - 新しいパスワードをバリデーション
Route: completePasswordResetRoute - POST /auth/reset-password パスワード更新付き

使用法:

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


// データベース設定付き
app.use('/api', defService(partial(features.completePasswordResetFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/reset-password

`refreshTokenFeature`

アクセストークンを更新するためのスキーマバリデーションとルーティングを含むトークン更新機能。

目的: トークンローテーションとセキュリティ対策を含むトークン更新を処理

機能構成:

Schema: refreshTokenSchema - リクエストボディ内のリフレッシュトークンをバリデーション
Routes: refreshTokenRoute - POST /auth/token/refresh

使用法:

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

// データベース設定付き（ハンドラーはdataStoresが必要）:
app.use('/api', defService(partial(features.refreshTokenFeature, [{ dataStores: db }])));

APIエンドポイント: POST /api/auth/token/refresh

`deleteRefreshTokensFeature`

アイデンティティのリフレッシュトークンを削除するためのスキーマバリデーションとルーティングを含むリフレッシュトークン削除機能。

目的: 特定のアイデンティティのリフレッシュトークンの安全な削除を処理

機能構成:

Schema: deleteRefreshTokensSchema - アイデンティティIDパスパラメータをバリデーション
Routes: deleteRefreshTokensRoute - DELETE /auth/:identityId/refresh-tokens 認証とアクセスバリデーション付き

使用法:

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

// データベース設定付き（ハンドラーはdataStoresが必要）:
app.use('/api', defService(partial(features.deleteRefreshTokensFeature, [{ dataStores: db }])));

APIエンドポイント: DELETE /api/auth/:identityId/refresh-tokens

🎯 概要​

📋 機能構造​

🔧 利用可能な認証機能​

loginWithCredentialsFeature​

verifyMfaCodeFeature​

resendMfaCodeFeature​

loginWithOnetimeTokenFeature​

registerCredentialsFeature​

emailVerificationFeature​

confirmEmailFeature​

changeEmailFeature​

checkTokenFeature​

confirmNewEmailFeature​

sendResetPasswordLinkEmailFeature​

changePasswordFeature​

activateFeature​

deactivateFeature​

completePasswordResetFeature​

refreshTokenFeature​

deleteRefreshTokensFeature​

🎯 概要

📋 機能構造

🔧 利用可能な認証機能

`loginWithCredentialsFeature`

`verifyMfaCodeFeature`

`resendMfaCodeFeature`

`loginWithOnetimeTokenFeature`

`registerCredentialsFeature`

`emailVerificationFeature`

`confirmEmailFeature`

`changeEmailFeature`

`checkTokenFeature`

`confirmNewEmailFeature`

`sendResetPasswordLinkEmailFeature`

`changePasswordFeature`

`activateFeature`

`deactivateFeature`

`completePasswordResetFeature`

`refreshTokenFeature`

`deleteRefreshTokensFeature`