🪪 チャットバリデーター

チャットバリデーターは、Nodeblocksアプリケーションでチャット関連操作のバリデーション関数を提供します。これらのバリデーターは、チャットチャネル、メッセージ、会話の適切なアクセス制御とデータバリデーションを確保します。

---

🎯 概要

チャットバリデーターは以下の目的で設計されています：

• チャネルアクセスのバリデーション - 所有権と権限に基づく
• チャット操作の適切なメッセージアクセスの確保 - セキュアな操作
• 複数のアクセスパターンのサポート - 所有者、管理者、メンバー
• チャット固有のバリデーションロジックの処理 - セキュアな操作
• チャットワークフロー用の再利用可能なバリデーションの提供 - 再利用性

---

📋 チャットバリデータータイプ

アクセス制御バリデーター

チャットリソースのユーザー権限をチェックするバリデーター。

---

🔧 利用可能なチャットバリデーター

hasSubscription

アイデンティティが指定されたチャネルにサブスクライブされていることをバリデーションします。

目的: 関連リソースにアクセスする前にユーザーがチャネルにサブスクライブされていることを確保

パラメータ:

• channelIdPathInPayload: ペイロード内のchannelIdへのタプルパス
• subscribedIdPathInPayload (optional): ペイロード内のsubscribedIdへのタプルパス; デフォルトは認証されたアイデンティティ

戻り値: void - サブスクリプションが存在する場合に通過

スロー:

• NodeblocksError (500) with message "db.subscriptions is not set"
• NodeblocksError (401) with message "Invalid token"
• NodeblocksError (400) with message "Invalid channel ID"
• NodeblocksError (400) with message "Invalid subscribed ID"
• NodeblocksError (500) with message "Failed to fetch subscription"
• NodeblocksError (403) with message "Identity is not subscribed to the channel"

使用例:

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

const { hasSubscription } = validators;

withRoute({
  -- snip --
  validators: [
    hasSubscription(['requestParams', 'channelId'])
  ]
});

---

ownsSubscription

認証されたユーザーアクセス用のサブスクリプション所有権バリデーター。

目的: サブスクリプション所有者（サブスクライブされたアイデンティティ）のみがサブスクリプションを変更できることを確保

パラメータ:

• resourceIdPathInPayload: ペイロード内のsubscriptionIdへのタプルパス（例: ['requestParams', 'subscriptionId']）

戻り値: void - 認証されたアイデンティティがサブスクリプションを所有している場合に通過

スロー:

• NodeblocksError (401) with message "Invalid token"
• NodeblocksError (500) with message "Resource does not exist"
• NodeblocksError (400) with message "Invalid resource ID"
• NodeblocksError (403) with message "Failed to fetch resource"
• NodeblocksError (403) with message "Invalid owner ID"
• NodeblocksError (403) with message "Identity is not the owner of the resource"

使用例:

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

const { ownsSubscription } = validators;

withRoute({
  -- snip --
  validators: [
    ownsSubscription(['requestParams', 'subscriptionId'])
  ]
});

---

ownsChannel

認証されたユーザーアクセス用のチャットチャネル所有権バリデーター。

目的: チャネル所有者のみがチャネルにアクセス/変更できることを確保

パラメータ:

• resourceIdPathInPayload: ペイロード内のchannelIdへのタプルパス（例: ['requestParams', 'channelId']）

戻り値: void - 認証されたアイデンティティがチャネルを所有している場合に通過

スロー:

• NodeblocksError (401) with message "Invalid token"
• NodeblocksError (500) with message "Resource does not exist"
• NodeblocksError (400) with message "Invalid resource ID"
• NodeblocksError (403) with message "Failed to fetch resource"
• NodeblocksError (403) with message "Invalid owner ID"
• NodeblocksError (403) with message "Identity is not the owner of the resource"

使用例:

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

const { ownsChannel } = validators;

withRoute({
  -- snip --
  validators: [
    ownsChannel(['requestParams', 'channelId'])
  ]
});

---

ownsMessage

認証されたユーザーアクセス用のチャットメッセージ所有権バリデーター。

目的: メッセージ送信者のみがメッセージにアクセス/変更できることを確保

パラメータ:

• resourceIdPathInPayload: ペイロード内のmessageIdへのタプルパス（例: ['requestParams', 'messageId']）

戻り値: void - 認証されたアイデンティティが送信者である場合に通過

スロー:

• NodeblocksError (401) with message "Invalid token"
• NodeblocksError (500) with message "Resource does not exist"
• NodeblocksError (400) with message "Invalid resource ID"
• NodeblocksError (403) with message "Failed to fetch resource"
• NodeblocksError (403) with message "Invalid owner ID"
• NodeblocksError (403) with message "Identity is not the owner of the resource"

使用例:

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

const { ownsMessage } = validators;

withRoute({
  -- snip --
  validators: [
    ownsMessage(['requestParams', 'messageId'])
  ]
});

---

validateChannelAccess

許可されたサブジェクトとトークン情報に基づいてチャネルアクセスをバリデーションします。

非推奨

このバリデーターは非推奨です。
代替: ownsChannel。

目的: ユーザーが適切なチャネル所有権と権限を持っていることを確保

パラメータ:

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

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

スロー:

• NodeblocksError (401) with message "App token is not valid" or "User token is not valid" for invalid tokens
• NodeblocksError (400) with message "must have ownerId when creating a new channel" for missing ownerId on new channels
• NodeblocksError (403) with message "Channel has no owner" for channels without owner
• NodeblocksError (403) with message "User is not authorized to access this channel" for unauthorized access
• NodeblocksError (404) with message "Channel not found" if channel doesn't exist
• NodeblocksError (401) with message "Token does not have a valid access type" for invalid token types

サポート対象サブジェクト:

• 'owner' - チャネル所有者アクセス

Channel ID Sources (checked in order):

• payload.context.data.channelId
• payload.params.requestParams.channelId
• payload.params.requestQuery.channelId
• payload.params.requestBody.channelId

Owner ID Sources (for new channels):

• payload.context.data.ownerId
• payload.params.requestBody.ownerId

使用例:

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

const { validateChannelAccess } = validators;

withRoute({
  -- snip --
  validators: [validateChannelAccess(['owner'])]
});
withRoute({
  -- snip --
  validators: [validateChannelAccess(['owner', 'admin'])]
});

---

validateMessageAccess

許可されたサブジェクトとトークン情報に基づいてメッセージアクセスをバリデーションします。

非推奨

このバリデーターは非推奨です。
代替: ownsMessage。

目的: ユーザーが適切なメッセージ所有権と権限を持っていることを確保

パラメータ:

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

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

スロー:

• NodeblocksError (401) with message "App token is not valid" or "User token is not valid" for invalid tokens
• NodeblocksError (400) with message "must have senderId when creating a new message" for missing senderId on new messages
• NodeblocksError (403) with message "Message has no sender" for messages without sender
• NodeblocksError (403) with message "User is not authorized to access this message" for unauthorized access
• NodeblocksError (404) with message "Message not found" if message doesn't exist
• NodeblocksError (401) with message "Token does not have a valid access type" for invalid token types

サポート対象サブジェクト:

• 'owner' - メッセージ送信者アクセス

Message ID Sources (checked in order):

• payload.context.data.messageId
• payload.params.requestParams.messageId
• payload.params.requestQuery.messageId
• payload.params.requestBody.messageId

Sender ID Sources (for new messages):

• payload.context.data.senderId
• payload.params.requestBody.senderId

使用例:

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

const { validateMessageAccess } = validators;

// Message sender access
withRoute({
  -- snip --
  validators: [validateMessageAccess(['owner'])]
});

// Message sender or admin access
withRoute({
  -- snip --
  validators: [validateMessageAccess(['owner', 'admin'])]
});

hasOrganizationAccessToMessageTemplate

許可されたロールとテンプレートIDに基づいて、チャットメッセージテンプレートへの組織メンバーアクセスをバリデーションします。

目的: 認証されたアイデンティティが許可されたロールを持つテンプレートの組織のメンバーであることを確保

パラメータ:

• allowedRoles: string[] - 許可された組織ロール、例: ['owner','admin']
• messageTemplateIdPathInPayload - テンプレートIDへのタプルパス、例: ['requestParams','messageTemplateId']

戻り値: void - アクセスが許可されている場合は通過、それ以外の場合はスロー

スロー:

• NodeblocksError (401) with message "Invalid token"
• NodeblocksError (500) with message "Chat message templates collection is not set"
• NodeblocksError (404) with message "Chat message template not found"
• NodeblocksError (403) with message "Must be an admin to access this resource" (template without organizationId)
• NodeblocksError (500) with message "Organizations collection is not set"
• NodeblocksError (404) with message "Organization not found"
• NodeblocksError (403) with message "Identity is not allowed access to this resource"

使用例:

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

const { hasOrganizationAccessToMessageTemplate } = validators;

withRoute({
  // ...
  validators: [
    hasOrganizationAccessToMessageTemplate(
      ['owner','admin'],
      ['requestParams','messageTemplateId']
    )
  ]
});

---

channelExists

データベース内にチャットチャネルが存在することをバリデーションします。

目的: チャネルに対する操作を許可する前にチャネルが存在することを確保

パラメータ:

• channelIdPathInPayload: [T, ...T[]] - リクエストペイロードからチャネルIDを抽出するタプルパス配列（例: ['params', 'requestParams', 'channelId']）

戻り値: void - チャネルが存在する場合に通過

スロー:

• NodeblocksError (500) with message "Missing channel collection" if chatChannels collection is not configured
• NodeblocksError (500) with message "Unknown db error" for database operation failures
• NodeblocksError (404) with message "Channel does not exist" if channel is not found

ハンドラープロセス:

• 入力: RouteHandlerPayload with database context and channel ID path in payload
• プロセス: Extracts channel ID from payload using provided path, queries database for channel existence
• 出力: Throws NodeblocksError if validation fails; continues if channel exists
• エラー: 500 for missing collection or database errors, 404 if channel doesn't exist

使用例:

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

const { channelExists } = validators;

// Used in route composition:
withRoute({
  handler: compose(channelHandler),
  validators: [
    isAuthenticated(),
    channelExists(['params', 'requestParams', 'channelId'])
  ]
});

使用例シナリオ:

// Validating channel for read state updates:
withRoute({
  method: 'PUT',
  path: '/channels/:channelId/read-state',
  validators: [
    isAuthenticated(),
    channelExists(['params', 'requestParams', 'channelId']),
    hasSubscription(['params', 'requestParams', 'channelId'])
  ]
});

// Validating channel for subscription operations:
withRoute({
  method: 'POST',
  path: '/channels/:channelId/subscriptions',
  validators: [
    isAuthenticated(),
    channelExists(['params', 'requestParams', 'channelId'])
  ]
});

---

🔗 関連ドキュメント

• チャットスキーマ - チャットデータバリデーションと契約
• チャットハンドラー - チャットビジネスロジック関数
• チャットルート - チャットHTTPエンドポイント定義
• チャット機能 - チャット構成機能