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

🔍 認証スキーマ

認証スキーマは、Nodeblocksアプリケーションで認証データのバリデーションを行うためのJSON Schema定義を提供します。これらのスキーマは安全な認証フローを確保し、認証関連のAPIエンドポイントに対する明確な契約を提供します。

🎯 概要​

認証スキーマは以下の目的で設計されています：

  • 認証データのバリデーション - 処理前の検証
  • 複数の認証方法のサポート（OAuth、メール/パスワード）
  • 適切なバリデーションによる安全な認証の確保
  • メール確認ワークフローの有効化
  • 強化されたセキュリティのためのデバイスフィンガープリンティングのサポート

📋 認証スキーマタイプ​

プロバイダー認証スキーマ​

OAuthおよびサードパーティ認証のバリデーション。

認証情報認証スキーマ​

メール/パスワード認証のバリデーション。

アイデンティティスキーマ​

複数の方法をサポートする柔軟な認証。

メール確認スキーマ​

メール確認と確認ワークフロー。

🔧 利用可能な認証スキーマ​

passwordSchema​

セキュリティ要件とパターンマッチングを含むパスワードバリデーションスキーマ。

目的: パスワードバリデーションの基本スキーマとして機能し、他の認証スキーマで使用される

スキーマ詳細:

  • Type: object
  • 必須フィールド: なし
  • Additional Properties: false
  • Properties:
    • password: string — 8-24文字；少なくとも1つの小文字と1つの数字；?/_-を許可

使用例:

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

const { passwordSchema } = schemas;

const validate = ajv.compile(passwordSchema as SchemaDefinition);
const isValid = validate({ password: 'securePass123' });

providerSchema​

OAuthおよびサードパーティ認証用のプロバイダー認証スキーマ。

目的: OAuthプロバイダー認証データをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: provider、providerId
  • Additional Properties: false（厳密なバリデーション）
  • Properties:
    • provider: string - OAuthプロバイダー名
    • providerId: string - プロバイダー固有のユーザーID

使用例:

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

const { providerSchema } = schemas;
const validate = ajv.compile(providerSchema as SchemaDefinition);
const isValid = validate({ provider: 'google', providerId: '12345' });

credentialsSchema​

メール/パスワード認証用の認証情報認証スキーマ。

目的: メール/パスワード認証データをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: email、password
  • Additional Properties: false（厳密なバリデーション）
  • Properties:
    • email: string - アイデンティティメールアドレス
    • emailVerified: boolean - メール確認ステータス（デフォルト: false）
    • password: string - ユーザーパスワード

使用例:

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

const { credentialsSchema } = schemas;
const validate = ajv.compile(credentialsSchema as SchemaDefinition);
const isValid = validate({ email: 'identity@example.com', password: 'password123' });

changePasswordSchema​

ユーザーアカウント用の現在のパスワードと新しいパスワードのバリデーションを含むパスワード変更スキーマ。

目的: セキュリティ要件を含むパスワード変更リクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: password、newPassword
  • Additional Properties: false（厳密なバリデーション）
  • パラメータ: identityId（パスパラメータ）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • password: string - 確認用の現在のパスワード
    • newPassword: string - セキュリティ要件を含む新しいパスワード

新しいパスワード要件:

  • 長さ: 8-24文字
  • パターン: 少なくとも1つの小文字と1つの数字を含む必要がある
  • 許可される文字: 文字、数字、特殊文字（?/_-）
  • バリデーション: 正規表現パターンがnewPasswordのセキュリティ要件を強制
  • Identity ID: アイデンティティ識別のためのパスパラメータとして必須

使用例:

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

const { changePasswordSchema } = schemas;

// Apply to feature composition:
export const changePasswordFeature = compose(changePasswordSchema, changePasswordRoute);

completePasswordResetSchema​

アカウント回復用のパスワードバリデーションを含むパスワードリセット完了スキーマ。

目的: セキュリティ要件を含むパスワードリセット完了リクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: password
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • password: string - セキュリティ要件を含む新しいパスワード

パスワード要件:

  • 長さ: 8-24文字
  • パターン: 少なくとも1つの小文字と1つの数字を含む必要がある
  • 許可される文字: 文字、数字、特殊文字（?/_-）
  • バリデーション: passwordSchemaのセキュリティ要件を継承
  • ワークフロー: リセットリンクを受信した後のパスワードリセットワークフローで使用

使用例:

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

const { completePasswordResetSchema } = schemas;

// Apply to feature composition:
export const completePasswordResetFeature = compose(completePasswordResetSchema, completePasswordResetRoute);

activateSchema​

アカウント有効化用のアイデンティティバリデーションを含むアイデンティティ有効化スキーマ。

目的: アイデンティティIDバリデーションを含むアイデンティティ有効化リクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: identityId
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • identityId: string - 有効化用のユーザーアイデンティティ識別子

使用例:

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

const { activateSchema } = schemas;

// Apply to feature composition:
export const activateFeature = compose(activateSchema, activateRoute);

deactivateSchema​

アカウント無効化用のアイデンティティバリデーションを含むアイデンティティ無効化スキーマ。

目的: アイデンティティIDバリデーションを含むアイデンティティ無効化リクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: identityId
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • identityId: string - 無効化用のユーザーアイデンティティ識別子

使用例:

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

const { deactivateSchema } = schemas;

// Apply to feature composition:
export const deactivateFeature = compose(deactivateSchema, deactivateRoute);

identitySchema​

プロバイダー認証と認証情報認証の両方をサポートするアイデンティティスキーマ。

目的: 複数の認証方法をサポートする認証データをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: provider+providerId または email+passwordのいずれか
  • Additional Properties: false（厳密なバリデーション）
  • Validation: provider+providerId または email+passwordのいずれかが必要
  • Content-Type: application/json
  • Request Body: required

使用例:

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

const { identitySchema } = schemas;

const identitySchema = identitySchema({});
const validate = ajv.compile(identitySchema.schemas as SchemaDefinition);

// Provider auth
const isValidProvider = validate({ provider: 'google', providerId: '12345' });

// Credentials auth
const isValidCredentials = validate({ email: 'identity@example.com', password: 'password123' });

loginWithCredentialsSchema​

アイデンティティ認証用のログイン認証情報スキーマ。

目的: オプションのデバイスフィンガープリンティングを含むログインリクエストデータをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: email、password
  • Optional Fields: fingerprint
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required

使用例:

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

const { loginWithCredentialsSchema } = schemas;

const loginSchema = loginWithCredentialsSchema({});
const validate = ajv.compile(loginSchema.schemas as SchemaDefinition);
const isValid = validate({
  email: 'identity@example.com',
  password: 'password123',
  fingerprint: 'device-fingerprint-hash'
});

resendMfaCodeSchema​

認証用のトークンバリデーションを含むMFAコード再送信スキーマ。

目的: 新しい確認コードが必要なユーザー向けのMFAコード再送信リクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: token
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • token: string - 初期ログイン試行からのMFAチャレンジトークン

使用ケース:

  • ユーザーが初期MFAコードメールを受信しなかった
  • ユーザーが入力する前にMFAコードが期限切れになった
  • メール配信の遅延または失敗
  • ユーザーが誤ってメールを削除した

セキュリティ機能:

  • 以前のMFAトークンを無効化
  • セキュリティのために新しいMFAコードを生成
  • 新しいMFAトークンを発行
  • トークンベースの確認フローを維持

使用例:

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

const { resendMfaCodeSchema } = schemas;

// Apply to feature composition:
export const resendMfaCodeFeature = compose(resendMfaCodeSchema, resendMfaCodeRoute);

// Example valid request:
const validRequest = {
  token: 'encrypted-mfa-challenge-token'
};

リクエスト例:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

レスポンス例（成功）:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

verifyMfaCodeSchema​

トークンとコードのバリデーションを含むMFAコード確認スキーマ。

目的: MFAトークンとユーザー提供コードを含むMFAコード確認リクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: token、code
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • token: string - ログインエンドポイントから返されたMFAチャレンジトークン
    • code: string - ユーザー提供のMFA確認コード（メールから）

ワークフロー:

  1. ユーザーが認証情報でログインを試行
  2. システムがメールでMFAコードを送信し、MFAトークンを返す
  3. ユーザーがメールでMFAコードを受信
  4. ユーザーが確認のためにMFAトークンとコードを送信
  5. システムがコードをバリデーションし、アクセス/リフレッシュトークンを返す

セキュリティ機能:

  • トークンベースの確認によりリプレイ攻撃を防止
  • 使用後にワンタイムトークンを無効化
  • 時間制限付きトークンにより古いコードの使用を防止
  • 厳密なスキーマバリデーション

使用例:

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

const { verifyMfaCodeSchema } = schemas;

// Apply to feature composition:
export const verifyMfaCodeFeature = compose(verifyMfaCodeSchema, verifyMfaCodeRoute);

// Example valid request:
const validRequest = {
  token: 'encrypted-mfa-challenge-token',
  code: '123456'
};

リクエスト例:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456"
}

レスポンス例（成功）:

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

loginWithOnetimeTokenSchema​

安全な認証のためのトークンバリデーションを含むワンタイムトークンログインスキーマ。

目的: パスワードレス認証のためのワンタイムトークンログインリクエストをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: token
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • token: string - ワンタイム認証トークン（通常はマジックリンクから）

使用ケース:

  • マジックリンク認証
  • メールベースのパスワードレスログイン
  • パスワードなしでの安全なアカウントアクセス
  • 時間制限付き認証トークン

セキュリティ機能:

  • トークンはtype: 'onetime'を持つ必要がある
  • トークンはtarget: 'login'を持つ必要がある
  • トークンはワンタイム使用（ログイン後に無効化）
  • トークンにはユーザー検索用のアイデンティティIDが含まれる
  • トークンバリデーションにはフィンガープリントとリクエスト情報が含まれる

使用例:

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

const { loginWithOnetimeTokenSchema } = schemas;

// Apply to feature composition:
export const loginWithOnetimeTokenFeature = compose(
  loginWithOnetimeTokenSchema, 
  loginWithOnetimeTokenRoute
);

// Example valid request:
const validRequest = {
  token: 'encrypted-onetime-authentication-token'
};

リクエスト例:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

レスポンス例（成功）:

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

典型的なフロー:

  1. ユーザーがマジックリンクをリクエスト（別のエンドポイント）
  2. システムがtarget: 'login'でワンタイムトークンを生成
  3. システムがユーザーのメールにマジックリンクを送信
  4. ユーザーがリンクをクリックしてトークンを送信
  5. システムがトークンをバリデーションし、認証トークンを返す

registerCredentialsSchema​

メール/パスワードまたはトークン/パスワードのバリデーションを含むアイデンティティ登録スキーマ。

目的: アイデンティティ登録リクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: password（常に必須）
  • Optional Fields: email、token
  • Validation: email+password または token+passwordのいずれかが必要
  • Content-Type: application/json
  • Request Body: required

使用例:

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

const { registerCredentialsSchema } = schemas;

const registerSchema = registerCredentialsSchema({});
const validate = ajv.compile(registerSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'identity@example.com', 
  password: 'password123' 
});

sendVerificationEmailSchema​

メール確認送信リクエストをバリデーションするためのJSON Schema。

目的: メール確認送信エンドポイントのリクエストボディをバリデーション

スキーマ詳細:

  • Type: object
  • 必須フィールド: なし（すべてのフィールドがオプション）
  • Additional Properties: false（厳密なバリデーション）
  • パラメータ: identityId（パスパラメータ）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • fingerprint?: string - オプションのデバイスフィンガープリンティング

使用例:

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

const { sendVerificationEmailSchema } = schemas;

const verificationSchema = sendVerificationEmailSchema({});
const validate = ajv.compile(verificationSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  fingerprint: 'device-fingerprint-hash' 
});

confirmEmailSchema​

メール確認用のトークンバリデーションを含むメール確認スキーマ。

目的: メール確認リクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: token
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • token: string - メールからの確認トークン

使用例:

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

const { confirmEmailSchema } = schemas;

const confirmSchema = confirmEmailSchema({});
const validate = ajv.compile(confirmSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'verification-token-123' 
});

changeEmailSchema​

ユーザーメール更新用のアイデンティティバリデーションを含むメール変更スキーマ。

目的: メール変更リクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: email
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • パラメータ: identityId（パスパラメータ）
  • Properties:
    • email: string - アイデンティティアカウント用の新しいメールアドレス

使用例:

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

const { changeEmailSchema } = schemas;

const changeEmailSchema = changeEmailSchema({});
const validate = ajv.compile(changeEmailSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'newemail@example.com' 
});

checkTokenSchema​

必須トークンとオプションのターゲットパラメータを含むトークンバリデーションスキーマ。

目的: トークンバリデーションリクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: token
  • Optional Fields: target
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • token: string - バリデーションするJWTトークン文字列
    • target?: string - トークンバリデーションのターゲットコンテキスト（例: 'confirm-email'、'change-email'）

使用例:

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

const { checkTokenSchema } = schemas;

const checkTokenSchema = checkTokenSchema({});
const validate = ajv.compile(checkTokenSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'jwt-token-here',
  target: 'confirm-email'
});

confirmNewEmailSchema​

メール変更確認用のトークンバリデーションを含む新しいメール確認スキーマ。

目的: 新しいメール確認リクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: token
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • token: string - 新しいメールからの確認トークン

使用例:

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

const { confirmNewEmailSchema } = schemas;

const confirmNewEmailSchema = confirmNewEmailSchema({});
const validate = ajv.compile(confirmNewEmailSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  token: 'verification-token-123' 
});

sendResetPasswordLinkEmailSchema​

パスワード回復用のメールバリデーションを含むパスワードリセットメールスキーマ。

目的: パスワードリセットメールリクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: email
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • email: string - パスワードリセット用のユーザーメールアドレス

使用例:

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

const { sendResetPasswordLinkEmailSchema } = schemas;

const resetPasswordSchema = sendResetPasswordLinkEmailSchema({});
const validate = ajv.compile(resetPasswordSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  email: 'identity@example.com' 
});

refreshTokenSchema​

トークン更新リクエスト用のリフレッシュトークンバリデーションを含むトークン更新スキーマ。

目的: トークン更新リクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: refreshToken
  • Additional Properties: false（厳密なバリデーション）
  • Content-Type: application/json
  • Request Body: required
  • Properties:
    • refreshToken: string - 認証更新用のリフレッシュトークン

使用例:

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

const { refreshTokenSchema } = schemas;

// Apply to feature composition:
export const refreshTokenFeature = compose(refreshTokenSchema, refreshTokenRoute);

deleteRefreshTokensSchema​

アイデンティティパスパラメータバリデーションを含むリフレッシュトークン削除スキーマ。

目的: リフレッシュトークン削除リクエストのスキーマバリデーター

スキーマ詳細:

  • Type: object
  • 必須フィールド: identityId（パスパラメータ）
  • Additional Properties: false（厳密なバリデーション）
  • パラメータ: identityIdパスパラメータ

使用例:

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

const { deleteRefreshTokensSchema } = schemas;

// Apply to feature composition:
export const deleteRefreshTokensFeature = compose(deleteRefreshTokensSchema, deleteRefreshTokensRoute);

🔗 関連ドキュメント​