バージョン: 0.9.0 (最新)

🪪 共通バリデーター

共通バリデーターは、Nodeblocksアプリケーションの異なるドメインで使用できる汎用検証関数を提供します。これらのバリデーターは、あらゆるタイプのリソースに対して適切なパラメータ検証、認証、アクセス制御を保証します。

🎯 概要

共通バリデーターは以下の目的で設計されています：

ドメイン間で再利用する汎用検証関数の提供
あらゆるリソースに対する適切な認証と認可の保証
共通パラメータタイプの検証（UUID、数値、必須フィールド）
ロールベースと自己アクセスのパターンによる柔軟なアクセス制御のサポート
一貫した方法での横断的関心事の処理

📋 共通バリデータータイプ

認証バリデーター

あらゆるリソースの認証と認可をチェックするバリデーター。

パラメータバリデーター

パラメータの形式と存在をチェックするバリデーター。

🔧 利用可能な共通バリデーター

`some`

ORセマンティクスでバリデーターを合成します。いずれかのバリデーターがパスすればパスします。

目的: 1つだけ成功すればよい複数のバリデーターを結合します

パラメータ:

...args: Validator[] - ORロジックで合成するバリデーターの配列

戻り値: Validator - いずれかの入力バリデーターがパスすればパスする新しいバリデーター関数

スロー:

バリデーターが非NodeblocksErrorをスローした場合、メッセージ「Unknown error」でNodeblocksError（500）
すべてのバリデーターが失敗した場合、失敗したバリデーターからの最初のNodeblocksErrorをスロー

使用例:

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

const { some, hasOrgRole, ownsOrder } = validators;

withRoute({
  -- snip --
  validators: [
    some(
      hasOrgRole(['admin'], ['requestParams', 'organizationId']),
      ownsOrder(['requestParams', 'orderId'])
    )
  ]
});

`checkIdentityType`

認証されたユーザーのアイデンティティタイプが許可されたタイプと一致するかチェックします。

目的: アイデンティティタイプ設定に基づいてアクセスを制限します

パラメータ:

allowedTypes: 許可されたアイデンティティタイプキーのタプル（例: ['admin', 'moderator']）

戻り値: void - アイデンティティタイプが許可されている場合は通過します

スロー:

メッセージ「db.identities is not set」でNodeblocksError（500）
メッセージ「configuration.identity.typeIds is not set」でNodeblocksError（500）
メッセージ「Invalid token」でNodeblocksError（401）
メッセージ「Failed to fetch identity」でNodeblocksError（403）
メッセージ「Invalid identity type ID」でNodeblocksError（403）
メッセージ「Identity is not authorized to access this resource」でNodeblocksError（403）

使用例:

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

const { checkIdentityType } = validators;

withRoute({
  -- snip --
  validators: [
    checkIdentityType(['admin', 'moderator'])
  ]
});

重要: レガシーパラメータバリデーター

以下のバリデーターはレガシーインターフェースを使用しており、後で非推奨となり削除されます：

requireParam

isUUID

isNumber

これらは標準の RouteHandlerPayload を受け入れません。代わりに、payload.params.requestParams を抽出して手動で渡します：
({ params: { requestParams } }) => requireParam('identityId')(requestParams)
({ params: { requestParams } }) => isUUID('identityId')(requestParams)
({ params: { requestParams } }) => isNumber('limit')(requestParams)
その結果、これらのレガシーバリデーターは compose() や some() などのヘルパーと直接合成できません。合成には、標準のバリデーターまたは通常のペイロードシグネチャに従うカスタムバリデーターを優先してください。

`validateResourceAccess`

許可されたサブジェクトとトークンタイプに基づいてリソースアクセスを検証します。

非推奨

このバリデーターは非推奨です。
代替: 自己アクセスのチェックには isSelf、アイデンティティタイプの使用には checkIdentityType を使用してください。

目的: あらゆるリソースタイプ用の汎用アクセス制御バリデーター

パラメータ:

allowedSubjects: string[] - 許可されたユーザータイプ/サブジェクトの配列
authenticate: Authenticator - 認証関数（オプション、デフォルト: getBearerTokenInfo）
payload: RouteHandlerPayload - リクエストコンテキストとデータを含む

戻り値: void - ユーザーが適切な権限を持っている場合は通過します

スロー:

メッセージ「App token is not valid」または「User token is not valid」でNodeblocksError（401）
メッセージ「Failed to find identity」でNodeblocksError（500）
メッセージ「Identity not found」でNodeblocksError（401）
メッセージ「Identity is not authorized to access this resource」でNodeblocksError（403）
メッセージ「Token does not have a valid access type」でNodeblocksError（401）

サポートされているサブジェクト:

'self' - ユーザーは自分のリソースにアクセスできます（IDベースのマッチング）
'admin' - 管理者アクセス（typeId: '100'）
'user' - 通常のユーザーアクセス（typeId: '001'）
'guest' - ゲストアクセス（typeId: '000'）

アイデンティティIDソース（自己アクセス用、順番にチェック）:

payload.context.data.identityId
payload.params.requestParams.identityId
payload.params.requestQuery.identityId
payload.params.requestBody.identityId

アイデンティティタイプ設定（デフォルト）:

{
  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 - パラメータの存在をチェックするバリデーター関数

スロー: メッセージ「Missing required parameter: [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形式をチェックするバリデーター関数

スロー: メッセージ「Invalid UUID format for parameter: [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 - 数値変換をチェックするバリデーター関数

スロー: メッセージ「Parameter [parameterName] must be a number」でError

使用例:

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

const { isNumber } = validators;

withRoute({
  -- snip --
  validators: [({params: { requestParams }}) => isNumber('categoryNum')(requestParams)]
});

`ownsResource`

認証されたユーザーがデータベース内のリソースの所有者かどうかをチェックします。

目的: 専門的な所有権バリデーターを動かす汎用所有権バリデーター

パラメータ:

resource: 'chatChannels' | 'chatMessages' | 'orders' | 'users' | 'subscriptions' のいずれか
ownerIdPathInResource: リソース内の所有者フィールドへのタプルパス（例: ['identityId']）
resourceIdPathInPayload: ペイロード内のリソースIDへのタプルパス

戻り値: void - 認証されたアイデンティティがリソースを所有している場合は通過します

スロー:

メッセージ「Invalid token」でNodeblocksError（401）
メッセージ「Resource does not exist」でNodeblocksError（500）
メッセージ「Invalid resource ID」でNodeblocksError（400）
メッセージ「Failed to fetch resource」でNodeblocksError（403）
メッセージ「Invalid owner ID」でNodeblocksError（403）
メッセージ「Identity is not the owner of the resource」でNodeblocksError（403）

使用例:

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

const { ownsResource } = validators;

withRoute({
  -- snip --
  validators: [
    ownsResource('orders', ['identityId'], ['requestParams', 'orderId'])
  ]
});

🔗 関連ドキュメント

共通スキーマ - 共通データ検証と契約

🎯 概要​

📋 共通バリデータータイプ​

認証バリデーター​

パラメータバリデーター​

🔧 利用可能な共通バリデーター​

some​

checkIdentityType​

validateResourceAccess​

requireParam​

isUUID​

isNumber​

ownsResource​

🔗 関連ドキュメント​

🎯 概要

📋 共通バリデータータイプ

認証バリデーター

パラメータバリデーター

🔧 利用可能な共通バリデーター

`some`

`checkIdentityType`

`validateResourceAccess`

`requireParam`

`isUUID`

`isNumber`

`ownsResource`

🔗 関連ドキュメント