バージョン: 0.14.0 (最新)

🆔 アイデンティティサービス

アイデンティティサービスは、アイデンティティエンティティの取得、更新、削除、ロック、ロック解除、およびセキュリティ管理のための完全な REST API を提供します。NodeBlocks の関数型コンポジションアプローチで構築され、MongoDB とシームレスに統合します。

🚀 クイックスタート

import express from 'express';

import {middlewares, services, drivers} from '@nodeblocks/backend-sdk';

const {nodeBlocksErrorMiddleware} = middlewares;
const {identitiesService} = services;
const {withMongo} = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

express()
  .use(
    identitiesService(await connectToDatabase('identities'), {
      authSecrets: {
        authEncSecret: 'your-encryption-secret',
        authSignSecret: 'your-signing-secret',
      },
      authMode: 'bearer', // または 'cookie'
      identity: {
        typeIds: {
          admin: '100',
          guest: '000',
          regular: '001',
        },
      },
    }),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 エンドポイント概要

メソッド	パス	説明	認可
`GET`	`/identities/:identityId`	ID でアイデンティティを取得	アクセストークン必須（既定は `bearer`、`authMode: 'cookie'` の場合は `cookie`）。管理者のみ
`GET`	`/identities`	アイデンティティの一覧／フィルタ	アクセストークン必須（既定は `bearer`、`authMode: 'cookie'` の場合は `cookie`）。管理者のみ
`PATCH`	`/identities/:identityId`	アイデンティティを更新	アクセストークン必須（既定は `bearer`、`authMode: 'cookie'` の場合は `cookie`）。管理者のみ
`POST`	`/identities/:identityId/lock`	セキュリティ上の理由でアイデンティティをロック	アクセストークン必須（既定は `bearer`、`authMode: 'cookie'` の場合は `cookie`）。管理者のみ
`POST`	`/identities/:identityId/unlock`	ロックされたアイデンティティをロック解除	アクセストークン必須（既定は `bearer`、`authMode: 'cookie'` の場合は `cookie`）。管理者のみ
`DELETE`	`/identities/:identityId`	アイデンティティを削除	アクセストークン必須（既定は `bearer`、`authMode: 'cookie'` の場合は `cookie`）。管理者のみ

🗄️ エンティティスキーマ

アイデンティティエンティティは、自動生成されるベースフィールドと、アイデンティティ固有のデータで構成されます：

{
  "id": "string",
  "createdAt": "string (datetime)",
  "updatedAt": "string (datetime)",
  "email": "string",
  "emailVerified": "boolean",
  "password": "string (hashed)",
  "typeId": "string",
  "attempts": "number",
  "locked": "boolean",
  "deactivatedAt": "string (datetime) | null",
  "provider": "string",
  "providerId": "string"
}

フィールド詳細

フィールド	型	自動生成	必須	説明
`id`	string	✅	✅	一意識別子（UUID）
`createdAt`	datetime	✅	✅	作成日時
`updatedAt`	datetime	✅	✅	最終更新日時
`email`	string	❌	✅	ユーザーのメールアドレス
`emailVerified`	boolean	❌	❌	メール認証ステータス
`password`	string	❌	✅	ハッシュ化パスワード（bcrypt）
`typeId`	string	❌	❌	ユーザー種別識別子（例: 管理者は "100"）
`attempts`	number	❌	❌	ログイン試行回数
`locked`	boolean	❌	❌	アカウントロック状態
`deactivatedAt`	datetime または null	❌	❌	アカウント無効化日時。アクティブ時は `null`
`provider`	string	❌	❌	OAuth プロバイダー識別子
`providerId`	string	❌	❌	プロバイダー固有のアイデンティティ識別子

📝 注意: 自動生成フィールドはサービス側で設定され、作成/更新リクエストに含めないでください。

🔒 セキュリティに関する注意: セキュリティ上の理由から、password フィールドは API レスポンスで返されません。データベースには bcrypt で安全にハッシュ化して保存され、クライアントへ送信する前に除外されます。

🔐 認証ヘッダー

すべてのエンドポイントで、次のヘッダーを含めてください：

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

⚠️ 重要: 認可時にフィンガープリントを指定した場合、認証済みのすべてのリクエストで x-nb-fingerprint ヘッダーが必須です。欠如している場合は 401 Unauthorized が返ります。

🍪 Cookie 認証: authMode: 'cookie' の場合、保護されたルートは Cookie からアクセストークンを読み取ります。ホストアプリで cookie-parser を登録してください。

🔒 管理者アクセス必須: アイデンティティサービスのすべてのエンドポイントは管理者権限が必要です。アクセストークンは管理者権限を持つユーザー（デフォルトの typeId は "100"）のものである必要があります。非管理者は 403 Forbidden が返されます。

🔧 APIエンドポイント

1. アイデンティティの取得（ID指定）

一意のIDで特定のアイデンティティを取得します。

リクエスト:

Method: GET
Path: /identities/:identityId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: アクセストークン必須（既定は bearer、authMode: 'cookie' の場合は cookie）。管理者のみ

URL パラメータ:

パラメータ	型	必須	説明
`identityId`	string	✅	アイデンティティ一意識別子

レスポンスボディ:

フィールド	型	説明
`id`	string	アイデンティティ一意識別子
`email`	string	ユーザーのメールアドレス
`emailVerified`	boolean	メール認証ステータス
`typeId`	string	ユーザー種別識別子
`attempts`	number	ログイン試行回数
`locked`	boolean	アカウントロック状態
`createdAt`	string	作成日時
`updatedAt`	string	最終更新日時

バリデーション:

スキーマ検証: なし（GET リクエスト）
ルートバリデーション:
- 認証済みリクエスト（アクセストークン）必須
- 管理者ロール必須

リクエスト例:

curl {{host}}/identities/811ff0a3-a26f-447b-b68a-dd83ea4000b9 \
  -H "Authorization: Bearer your-access-token-here"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "attempts": 0,
  "email": "admin@example.com",
  "emailVerified": true,
  "locked": false,
  "createdAt": "2025-07-29T07:37:01.735Z",
  "id": "811ff0a3-a26f-447b-b68a-dd83ea4000b9",
  "updatedAt": "2025-07-29T07:39:36.564Z",
  "typeId": "100"
}

エラーレスポンス:

認可トークンが提供されていない場合:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "token could not be verified"
  }
}

指定IDのアイデンティティが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

予期しないエラーが発生した場合（DB接続問題など）:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to get identity"
  }
}

2. アイデンティティ一覧

アイデンティティの一覧を取得します。クエリパラメータはスキーマで検証されますが、ハンドラーは完全な配列を返し、サーバー側のページネーションは実装していません。

リクエスト:

Method: GET
Path: /identities
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: アクセストークン必須（既定は bearer、authMode: 'cookie' の場合は cookie）。管理者のみ

クエリパラメータ:

パラメータ	型	必須	説明
`name`	string	❌	スキーマで受け付けられ Mongo の `find` に渡される（既定のアイデンティティ文書には `name` フィールドがありません）
`page`	number	❌	スキーマで受け付けられ Mongo フィルターに渡される。ページネーションには使用されません
`limit`	number	❌	スキーマで受け付けられ Mongo フィルターに渡される。ページネーションには使用されません

レスポンスボディ:

フィールド	型	説明
`id`	string	アイデンティティ一意識別子
`email`	string	ユーザーのメールアドレス
`emailVerified`	boolean	メール認証ステータス
`typeId`	string	ユーザー種別識別子
`attempts`	number	ログイン試行回数
`locked`	boolean	アカウントロック状態
`createdAt`	string	作成日時
`updatedAt`	string	最終更新日時

バリデーション:

スキーマ検証: name（string）、page/limit（最小/最大制約のある整数）のクエリ検証。page/limit はページネーションには使われず、そのまま Mongo フィルターのクエリキーとして渡されます。
ルートバリデーション:
- 認証済みリクエスト（アクセストークン）必須
- 管理者ロール必須

リクエスト例:

全件取得:

curl {{host}}/identities \
  -H "Authorization: Bearer <access-token>"

名前でフィルタ:

curl "{{host}}/identities?name=admin" \
  -H "Authorization: Bearer <access-token>"

追加のクエリパラメータと組み合わせる場合:

curl "{{host}}/identities?name=admin&page=1&limit=20" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "attempts": 0,
    "email": "admin@example.com",
    "emailVerified": true,
    "locked": false,
    "createdAt": "2025-07-29T07:37:01.735Z",
    "id": "811ff0a3-a26f-447b-b68a-dd83ea4000b9",
    "updatedAt": "2025-07-29T07:39:36.564Z",
    "typeId": "100"
  },
  {
    "attempts": 0,
    "email": "user@example.com",
    "emailVerified": false,
    "locked": false,
    "createdAt": "2025-07-29T07:38:15.123Z",
    "id": "922ff1b4-b37g-558c-c79b-ee94fb5001c0",
    "updatedAt": "2025-07-29T07:38:15.123Z",
    "typeId": "001"
  }
]

エラーレスポンス:

リソースにアクセスする権限がない場合:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Identity is not authorized to access this resource"
  }
}

予期しないエラーが発生した場合（DB接続問題、フィルタ構文不正など）:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to find identities"
  }
}

3. アイデンティティ更新

部分更新で既存のアイデンティティを更新します。

リクエスト:

Method: PATCH
Path: /identities/:identityId
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: アクセストークン必須（既定は bearer、authMode: 'cookie' の場合は cookie）。管理者のみ

URL パラメータ:

パラメータ	型	必須	説明
`identityId`	string	✅	アイデンティティ一意識別子

リクエストボディ（オブジェクト必須。少なくとも1つのフィールドを指定）:

フィールド	型	必須	説明
`email`	string	❌	ユーザーのメールアドレス
`emailVerified`	boolean	❌	メール認証ステータス
`typeId`	string	❌	ユーザー種別識別子

レスポンスボディ:

フィールド	型	説明
`id`	string	アイデンティティ一意識別子
`email`	string	更新後のメールアドレス
`emailVerified`	boolean	更新後のメール認証ステータス
`typeId`	string	更新後のユーザー種別識別子
`attempts`	number	更新後のログイン試行回数
`locked`	boolean	更新後のアカウントロック状態
`createdAt`	string	作成日時
`updatedAt`	string	最終更新日時

バリデーション:

スキーマ検証: 基本的な検証（全フィールド任意、型チェック）
ルートバリデーション:
- 認証済みリクエスト（アクセストークン）必須
- 管理者ロール必須

注: 空の JSON オブジェクトは、更新ペイロードに少なくとも1つのフィールドが必要なため、ハンドラーにより 400 Identity data is required で拒否されます。

リクエスト例:

curl -X PATCH {{host}}/identities/811ff0a3-a26f-447b-b68a-dd83ea4000b9 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "email": "admin@example.com",
    "emailVerified": true,
    "typeId": "200"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "attempts": 0,
  "email": "admin@example.com",
  "locked": false,
  "createdAt": "2025-07-29T07:37:01.735Z",
  "id": "811ff0a3-a26f-447b-b68a-dd83ea4000b9",
  "updatedAt": "2025-07-29T07:42:07.611Z",
  "typeId": "200"
}

エラーレスポンス:

指定IDのアイデンティティが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

リクエストボディが空の場合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Identity data is required"
  }
}

更新操作でデータが変更されない場合（変更なし）:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Failed to update identity"
  }
}

予期しないエラーが発生した場合（DB接続問題など）:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to update identity"
  }
}

4. アイデンティティ削除

システムからアイデンティティを完全に削除します。

リクエスト:

Method: DELETE
Path: /identities/:identityId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: アクセストークン必須（既定は bearer、authMode: 'cookie' の場合は cookie）。管理者のみ

URL パラメータ:

パラメータ	型	必須	説明
`identityId`	string	✅	アイデンティティ一意識別子

レスポンスボディ:

フィールド	型	説明
なし	-	成功時はレスポンスボディなし

バリデーション:

スキーマ検証: なし（DELETE リクエスト）
ルートバリデーション:
- 認証済みリクエスト（アクセストークン）必須
- 管理者ロール必須

リクエスト例:

curl -X DELETE {{host}}/identities/be265523-7fea-44a1-a0a2-dc5dabdb9f0c \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

リソースにアクセスする権限がない場合:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Identity is not authorized to access this resource"
  }
}

指定IDのアイデンティティが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

予期しないエラーが発生した場合（DB接続問題など）:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": {
    "message": "Failed to delete identity"
  }
}

5. アイデンティティをロック

セキュリティ上の理由から、アイデンティティアカウントをロックしてアクセスを禁止します。

リクエスト:

メソッド: POST
パス: /identities/:identityId/lock
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: アクセストークン必須（既定は bearer、authMode: 'cookie' の場合は cookie）。管理者のみ

URL パラメータ:

パラメータ	型	必須	説明
`identityId`	string	✅	ロックするアイデンティティの一意識別子

レスポンスボディ:

フィールド	型	説明
なし	-	ロックエンドポイントは成功時にレスポンスボディを返しません

バリデーション: パスパラメータを検証し、認証済みの管理者ロールを要求します。

リクエスト例:

curl -X POST {{host}}/identities/be265523-7fea-44a1-a0a2-dc5dabdb9f0c/lock \
  -H "Authorization: Bearer <access-token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

ユーザーに権限がない場合:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Identity is not authorized to access this resource"
  }
}

アイデンティティが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

6. アイデンティティをロック解除

以前にロックしたアイデンティティアカウントのロックを解除し、アクセスを復元します。

リクエスト:

メソッド: POST
パス: /identities/:identityId/unlock
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: アクセストークン必須（既定は bearer、authMode: 'cookie' の場合は cookie）。管理者のみ

URL パラメータ:

パラメータ	型	必須	説明
`identityId`	string	✅	ロック解除するアイデンティティの一意識別子

レスポンスボディ:

フィールド	型	説明
なし	-	ロック解除エンドポイントは成功時にレスポンスボディを返しません

バリデーション: パスパラメータを検証し、認証済みの管理者ロールを要求します。

リクエスト例:

curl -X POST {{host}}/identities/be265523-7fea-44a1-a0a2-dc5dabdb9f0c/unlock \
  -H "Authorization: Bearer <access-token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

成功レスポンス:

HTTP/1.1 204 No Content

エラーレスポンス:

ユーザーに権限がない場合:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Identity is not authorized to access this resource"
  }
}

アイデンティティが存在しない場合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Identity not found"
  }
}

🗄️ データストア

コレクション	必須	説明
`identities`	✅	アイデンティティ文書

⚙️ 設定オプション

サービス設定

interface IdentitiesServiceConfiguration {
  authSecrets: {
    authEncSecret: string; // JWT encryption secret
    authSignSecret: string; // JWT signing secret
  };
  authMode?: 'bearer' | 'cookie'; // 未指定時は bearer 動作が既定
  identity?: {
    typeIds?: {
      admin: string; // Admin user type identifier
      guest: string; // Guest user type identifier
      regular: string; // Regular user type identifier
    };
  };
}

設定詳細

アイデンティティサービスの設定は、セキュリティとユーザー種別管理の論理グループに整理されています。

🔐 セキュリティ設定

authSecrets - JWT トークンのセキュリティシークレット

型: { authEncSecret: string; authSignSecret: string }
説明: JWT の暗号化および署名に使用する秘密鍵（トークン検証に使用）
必須: 本番環境では必須
子プロパティ:
- authEncSecret: JWT ペイロード暗号化の秘密鍵
- authSignSecret: JWT 署名検証の秘密鍵

👥 ユーザー種別設定

identity.typeIds - ユーザー種別識別子の設定

型: { admin?: string; guest?: string; regular?: string }
説明: ロールベースアクセス制御のためのカスタムユーザー種別識別子
デフォルト: undefined（デフォルトの種別検証を使用）
子プロパティ:
- admin: 管理者ユーザー種別の識別子
  - 型: string
  - 説明: 管理者ユーザーのカスタム識別子
  - 利用例: 管理操作のロールベースアクセス制御
  - 例: "admin", "administrator", "superuser"
- guest: ゲストユーザー種別の識別子
  - 型: string
  - 説明: ゲストユーザーのカスタム識別子
  - 利用例: 未認証/一時ユーザーの限定的アクセス
  - 例: "guest", "visitor", "anonymous"
- regular: 一般ユーザー種別の識別子
  - 型: string
  - 説明: 一般ユーザーのカスタム識別子
  - 利用例: 標準的なユーザー権限
  - 例: "user", "member", "customer"

設定例

const identityConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret',
  },
  identity: {
    typeIds: {
      admin: '100',
      guest: '000',
      regular: '001',
    },
  },
};

🚨 エラーハンドリング

アイデンティティサービスのエラーは、適切なHTTPステータスコードとJSON形式で返されます：

代表的なエラーコード

ステータス	エラーメッセージ	説明
400	Identity data is required	更新リクエストのボディが空
400	Failed to update identity	更新操作でデータが変更されない（変更なし）
401	token could not be verified	認可トークンがない/無効
403	Identity is not authorized to access this resource	要求操作に必要な権限が不足
404	Identity not found	GET/PATCH/DELETE/LOCK/UNLOCK の対象アイデンティティが存在しない
500	Failed to get identity	取得中のDB接続問題/予期せぬ失敗
500	Failed to find identities	一覧取得中のDB接続問題/フィルタ不正/予期せぬ失敗
500	Failed to update identity	更新中のDB接続問題/予期せぬ失敗
500	Failed to delete identity	削除中のDB接続問題/予期せぬ失敗

エラーレスポンス形式

{
  "error": {
    "message": "Error message description",
    "data": ["Additional error details"]
  }
}

🔗 関連ドキュメント

エラーハンドリング - エラーパターンの理解
スキーマコンポーネント - データ検証の概念
カスタムサービスチュートリアル - 独自サービスの構築
プロフィールサービス - プロフィール管理サービス

🚀 クイックスタート​

📋 エンドポイント概要​

🗄️ エンティティスキーマ​

フィールド詳細​

🔐 認証ヘッダー​

🔧 APIエンドポイント​

1. アイデンティティの取得（ID指定）​

2. アイデンティティ一覧​

3. アイデンティティ更新​

4. アイデンティティ削除​

5. アイデンティティをロック​

6. アイデンティティをロック解除​

🗄️ データストア​

⚙️ 設定オプション​

サービス設定​

設定詳細​

🔐 セキュリティ設定​

👥 ユーザー種別設定​

設定例​

🚨 エラーハンドリング​

代表的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

🗄️ エンティティスキーマ

フィールド詳細

🔐 認証ヘッダー

🔧 APIエンドポイント

1. アイデンティティの取得（ID指定）

2. アイデンティティ一覧

3. アイデンティティ更新

4. アイデンティティ削除

5. アイデンティティをロック

6. アイデンティティをロック解除

🗄️ データストア

⚙️ 設定オプション

サービス設定

設定詳細

🔐 セキュリティ設定

👥 ユーザー種別設定

設定例

🚨 エラーハンドリング

代表的なエラーコード

エラーレスポンス形式

🔗 関連ドキュメント