🔧 共通バリデーターブロック
共通バリデーターブロックは、NodeBlocks アプリケーションの異なるドメイン間で使用できる汎用検証関数を提供します。これらの検証機能は、任意のリソースタイプに対する適切なパラメータ検証、認証、アクセス制御を確保します。
🎯 概要
共通バリデーターブロックは次のことを目的として設計されています:
- ドメイン間で再利用するための汎用検証関数を提供する
- 任意のリソースに対する適切な認証と認可を確保する
- 共通パラメータタイプを検証する（UUID、数字、必須フィールド）
- ロールベースおよび自己アクセスパターンによる柔軟なアクセス制御をサポートする
- クロスカッティング懸念を一貫した方法で処理する
📋 共通バリデータータイプ
認証バリデーター
任意のリソースに対する認証と認可をチェックする検証機能。
パラメーターバリデーター
パラメータのフォーマットと存在をチェックする検証機能。
🔧 利用可能な共通バリデーター
some
OR セマンティクスで検証機能を構成します。いずれかの検証機能が成功すれば通過します。
目的: 1 つだけが成功すればよい複数の検証機能を組み合わせる
パラメーター:
...args:Validator[]- OR ロジックで構成する検証機能の配列
戻り値: Validator - いずれかの入力検証機能が成功すれば通過する新しい検証関数
スロー:
- NodeblocksError (500) with message "不明なエラー"（バリデーターが NodeblocksError 以外のエラーをスローした場合）
- すべてのバリデーターが失敗した場合、失敗したバリデーターからの最初の NodeblocksError をスロー
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { some, hasOrgRole, ownsOrder } = validators;
withRoute({
-- snip --
validators: [
some(
hasOrgRole(['admin'], ['requestParams', 'organizationId']),
ownsOrder(['requestParams', 'orderId'])
)
]
});
checkIdentityType
認証されたユーザーの ID タイプが許可されたタイプと一致するかどうかをチェックします。
目的: ID タイプ構成に基づいてアクセスをゲートします
パラメーター:
allowedTypes: 許可された ID タイプキーのタプル（例:['admin', 'moderator']）
戻り値: void - ID タイプが許可されている場合に通過します
スロー:
- NodeblocksError (500) with message "db.identities が設定されていません"
- NodeblocksError (500) with message "configuration.identity.typeIds が設定されていません"
- NodeblocksError (401) with message "無効なトークン"
- NodeblocksError (403) with message "ID の取得に失敗しました"
- NodeblocksError (403) with message "無効な ID タイプ ID"
- NodeblocksError (403) with message "ID はこのリソースにアクセスする権限がありません"
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { checkIdentityType } = validators;
withRoute({
-- snip --
validators: [
checkIdentityType(['admin', 'moderator'])
]
});
重要: レガシー パラメータ検証機能
以下の検証機能はレガシーインターフェースを使用しており、後で非推奨となり削除されます:
requireParamisUUIDisNumberこれらは標準の
RouteHandlerPayloadを受け入れません。代わりに、payload.params.requestParamsを抽出して手動で渡します:({ params: { requestParams } }) => requireParam('identityId')(requestParams)
({ params: { requestParams } }) => isUUID('identityId')(requestParams)
({ params: { requestParams } }) => isNumber('limit')(requestParams)その結果、これらのレガシー検証機能は、
compose()やsome()などのヘルパーで直接構成できません。通常のペイロード署名に従う標準検証機能またはカスタム検証機能を優先してください。
validateResourceAccess
許可されたサブジェクトとトークンタイプに基づいてリソースアクセスを検証します。
このバリデーターは非推奨です。
置き換え: isSelf（自己アクセスのチェック用）、checkIdentityType（ID タイプの使用用）。
目的: 任意のリソースタイプのための汎用アクセス制御検証機能
パラメーター:
allowedSubjects:string[]- 許可されたユーザータイプ/サブジェクトの配列authenticate:Authenticator- 認証関数（オプション、デフォルトは getBearerTokenInfo）payload:RouteHandlerPayload- リクエストコンテキストとデータを含む
戻り値: void - ユーザーが適切な権限を持っている場合に通過します
スロー:
- NodeblocksError (401) with message "アプリトークンが無効です" または "ユーザートークンが無効です"
- NodeblocksError (500) with message "ID の検索に失敗しました"
- NodeblocksError (401) with message "ID が見つかりません"
- NodeblocksError (403) with message "ID はこのリソースにアクセスする権限がありません"
- NodeblocksError (401) with message "トークンに有効なアクセスタイプがありません"
サポートされているサブジェクト:
'self'- ユーザーは自分のリソースにアクセスできます（ID ベースのマッチング）'admin'- 管理者アクセス（typeId: '100'）'user'- 通常ユーザーアクセス（typeId: '001'）'guest'- ゲストアクセス（typeId: '000'）
ID ソース（自己アクセスの場合、チェック順）:
payload.context.data.identityIdpayload.params.requestParams.identityIdpayload.params.requestQuery.identityIdpayload.params.requestBody.identityId
ID タイプ構成（デフォルト）:
{
admin: '100',
guest: '000',
user: '001'
}
アクセスロジック:
- アプリトークン: appId が有効であれば常に通過
- ユーザートークン:
'self'サブジェクトの場合: ID をリソース ID とマッチング- ロールサブジェクトの場合: typeId を構成された typeId とマッチング
- アクセスを許可するには少なくとも 1 つのサブジェクトが一致する必要がある
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { validateResourceAccess } = validators;
withRoute({
-- snip --
validators: [validateResourceAccess(['admin'])]
});
withRoute({
-- snip --
validators: [validateResourceAccess(['self', 'admin'])]
});
withRoute({
-- snip --
validators: [validateResourceAccess(['admin', 'user', 'guest'])]
});
requireParam
必須パラメーターが存在し、null でないことを確保する検証機能を作成します。
目的: パラメーター要件検証機能を作成するためのファクトリ関数
パラメーター:
key:string- 検証するパラメーター名
戻り値: Validator - パラメーターの存在をチェックする検証関数
スロー: "必須パラメーターがありません: [parameterName]" というメッセージの Error
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { requireParam } = validators;
withRoute({
-- snip --
validators: [({params: { requestParams }}) => requireParam('identityId')(requestParams)]
});
isUUID
パラメーターが有効な UUID v4 形式に従うことを確保する検証機能を作成します。
目的: UUID フォーマット検証機能を作成するためのファクトリ関数
パラメーター:
key:string- UUID として検証するパラメーター名
戻り値: Validator - UUID フォーマットをチェックする検証関数
スロー: "パラメーターの UUID 形式が無効です: [parameterName]" というメッセージの Error
UUID 形式: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx（x は 16 進数、y は 8、9、a、b のいずれか）
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { isUUID } = validators;
withRoute({
-- snip --
validators: [({params: { requestParams }}) => isUUID('categoryId')(requestParams)]
});
isNumber
パラメーターを有効な数値に変換できることを確保する検証機能を作成します。
目的: 数値フォーマット検証機能を作成するためのファクトリ関数
パラメーター:
key:string- 数値として検証するパラメーター名
戻り値: Validator - 数値変換をチェックする検証関数
スロー: "パラメーター [parameterName] は数値である必要があります" というメッセージの Error
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { isNumber } = validators;
withRoute({
-- snip --
validators: [({params: { requestParams }}) => isNumber('categoryNum')(requestParams)]
});
ownsResource
認証されたユーザーがデータベース内のリソースの所有者であるかどうかをチェックします。
目的: 特殊化された所有権検証機能を強化する汎用所有権検証機能
パラメーター:
resource: one of'chatChannels' | 'chatMessages' | 'orders' | 'users' | 'subscriptions'ownerIdPathInResource: リソース内の所有者フィールドへのタプルパス（例:['identityId']）resourceIdPathInPayload: payload 内のリソース ID へのタプルパス
戻り値: void - 認証された ID がリソースを所有する場合に通過します
スロー:
- NodeblocksError (401) with message "無効なトークン"
- NodeblocksError (500) with message "リソースが存在しません"
- NodeblocksError (400) with message "無効なリソース ID"
- NodeblocksError (403) with message "リソースの取得に失敗しました"
- NodeblocksError (403) with message "無効な所有者 ID"
- NodeblocksError (403) with message "ID はリソースの所有者ではありません"
使用例:
import { validators } from '@nodeblocks/backend-sdk';
const { ownsResource } = validators;
withRoute({
-- snip --
validators: [
ownsResource('orders', ['identityId'], ['requestParams', 'orderId'])
]
});
🔗 関連ドキュメント
- 共通スキーマブロック - 共通データ検証とコントラクト