バージョン: 0.9.0 (最新)

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

Identity Serviceは、CRUD、ロック/アンロック、セキュリティ管理を含む完全なライフサイクル操作でアイデンティティエンティティを管理するための完全な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', 'dev', 'user', 'password');

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

📋 エンドポイント概要

Method	Path	説明	認証が必要
`GET`	`/identities/:identityId`	IDでアイデンティティを取得	✅ 管理者
`GET`	`/identities`	アイデンティティをリスト/フィルタ	✅ 管理者
`PATCH`	`/identities/:identityId`	アイデンティティを更新	✅ 管理者
`POST`	`/identities/:identityId/lock`	セキュリティのためにアイデンティティをロック	✅ 管理者
`POST`	`/identities/:identityId/unlock`	ロックされたアイデンティティをアンロック	✅ 管理者
`DELETE`	`/identities/:identityId`	アイデンティティを削除	✅ 管理者

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

アイデンティティエンティティは、基本フィールド（自動生成）とアイデンティティ固有のデータを組み合わせます：

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

フィールド詳細

Field	Type	自動生成	必須	説明
`id`	string	✅	✅	一意の識別子（UUID）
`createdAt`	datetime	✅	✅	作成タイムスタンプ
`updatedAt`	datetime	✅	✅	最終更新タイムスタンプ
`email`	string	❌	✅	ユーザーのメールアドレス
`emailVerified`	boolean	❌	❌	メール確認ステータス
`password`	string	❌	✅	ハッシュ化されたパスワード（bcrypt）
`typeId`	string	❌	❌	ユーザータイプ識別子（例：管理者の場合は"100"）
`attempts`	number	❌	❌	ログイン試行回数
`locked`	boolean	❌	❌	アカウントロックステータス

📝 注記: 自動生成フィールドはサービスによって設定され、作成/更新リクエストに含めるべきではありません。

🔒 セキュリティ注記: セキュリティ上の理由により、passwordフィールドはAPIレスポンスで返されることはありません。bcryptハッシュを使用してデータベースに安全に保存されますが、クライアントにレスポンスを送信する前にフィルタリングされます。

🔐 認証ヘッダー

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

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

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

🔒 管理者アクセスが必要: すべてのIdentity Serviceエンドポイントには管理者権限が必要です。bearerトークンは管理者権限を持つユーザーに属している必要があります（デフォルトではtypeId: "100"）。管理者以外のユーザーは403 Forbiddenレスポンスを受け取ります。

🔧 APIエンドポイント

1. IDでアイデンティティを取得

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

リクエスト:

Method: GET
Path: /identities/:identityId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`identityId`	string	✅	一意のアイデンティティ識別子

レスポンスボディ:

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

バリデーション:

スキーマバリデーション: なし（GETリクエスト）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

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"
  }
}

予期しないエラーが発生した場合（データベース接続の問題など）:

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

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

2. アイデンティティのリスト取得

オプションのフィルタリングとページネーションを使用してアイデンティティのリストを取得します。

リクエスト:

Method: GET
Path: /identities
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者）

クエリパラメータ:

Parameter	Type	必須	説明
`name`	string	❌	名前でアイデンティティをフィルタ
`page`	number	❌	ページ番号（1-1000）
`limit`	number	❌	ページあたりの項目数（1-50）

レスポンスボディ:

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

バリデーション:

スキーマバリデーション: name（文字列）、page、limit（最小/最大制約付き整数）のクエリパラメータバリデーション
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

すべてのアイデンティティをリスト:

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": "User is not authorized to access this resource"
  }
}

予期しないエラーが発生した場合（データベース接続の問題、無効なフィルタ構文など）:

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

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

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

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

リクエスト:

Method: PATCH
Path: /identities/:identityId
Headers:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`identityId`	string	✅	一意のアイデンティティ識別子

リクエストボディ（すべてのフィールドはオプション）:

Field	Type	必須	説明
`email`	string	❌	ユーザーのメールアドレス
`emailVerified`	boolean	❌	メール確認ステータス
`typeId`	string	❌	ユーザータイプ識別子

レスポンスボディ:

Field	Type	説明
`id`	string	一意のアイデンティティ識別子
`email`	string	更新されたメールアドレス
`emailVerified`	boolean	更新されたメール確認ステータス
`typeId`	string	更新されたユーザータイプ識別子
`attempts`	number	更新されたログイン試行回数
`locked`	boolean	更新されたアカウントロックステータス
`createdAt`	string	作成タイムスタンプ
`updatedAt`	string	最終更新タイムスタンプ

バリデーション:

スキーマバリデーション: 基本バリデーション（すべてのフィールドはオプション、型チェック）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

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": "Failed to update identity"
  }
}

予期しないエラーが発生した場合（データベース接続の問題など）:

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

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

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

システムからアイデンティティを永続的に削除します。

リクエスト:

Method: DELETE
Path: /identities/:identityId
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`identityId`	string	✅	一意のアイデンティティ識別子

レスポンスボディ:

Field	Type	説明
レスポンスボディなし	-	削除エンドポイントは成功時にレスポンスボディを返しません

バリデーション:

スキーマバリデーション: なし（DELETEリクエスト）
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

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": "User is not authorized to access this resource"
  }
}

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

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

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

予期しないエラーが発生した場合（データベース接続の問題など）:

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

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

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

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

リクエスト:

Method: POST
Path: /identities/:identityId/lock
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`identityId`	string	✅	ロックする一意のアイデンティティ識別子

レスポンスボディ:

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

バリデーション:

スキーマバリデーション: パスパラメータバリデーション
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

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": "User is not authorized to access this resource"
  }
}

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

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

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

6. アイデンティティのアンロック

以前にロックされたアイデンティティアカウントをアンロックしてアクセスを復元します。

リクエスト:

Method: POST
Path: /identities/:identityId/unlock
Headers:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
Authorization: Bearerトークンが必要（管理者）

URLパラメータ:

Parameter	Type	必須	説明
`identityId`	string	✅	アンロックする一意のアイデンティティ識別子

レスポンスボディ:

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

バリデーション:

スキーマバリデーション: パスパラメータバリデーション
ルートバリデーター:
- 認証済みリクエストが必要（bearerトークン）
- 管理者ロールが必要

リクエスト例:

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": "User is not authorized to access this resource"
  }
}

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

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

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

⚙️ 設定オプション

サービス設定

interface IdentitiesServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT encryption secret
    authSignSecret: string;   // JWT signing secret
  };
  identity?: {
    typeIds?: {
      admin: string;          // Admin user type identifier
      guest: string;          // Guest user type identifier
      regular: string;        // Regular user type identifier
    };
  };
}

設定詳細

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

🔐 セキュリティ設定

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

Type: { authEncSecret: string; authSignSecret: string }
説明: JWT暗号化と署名のためのシークレットキー（トークン検証に使用）
必須: はい（本番環境の場合）
子プロパティ:
- authEncSecret: JWTペイロード暗号化のためのシークレットキー
- authSignSecret: JWT署名検証のためのシークレットキー

👥 ユーザータイプ設定

identity.typeIds - ユーザータイプ識別子設定

Type: { admin?: string; guest?: string; regular?: string }
説明: ロールベースアクセス制御のためのカスタムユーザータイプ識別子
デフォルト: undefined（デフォルトの型検証を使用）
子プロパティ:
- admin: 管理者ユーザータイプ識別子
  - Type: string
  - 説明: 管理者ユーザー用のカスタム識別子
  - 使用例: 管理操作のためのロールベースアクセス制御
  - 例: "admin", "administrator", "superuser"
- guest: ゲストユーザータイプ識別子
  - Type: string
  - 説明: ゲストユーザー用のカスタム識別子
  - 使用例: 認証されていないまたは一時的なユーザー向けの限定アクセス
  - 例: "guest", "visitor", "anonymous"
- regular: 通常ユーザータイプ識別子
  - Type: 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形式で返されます：

一般的なエラーコード

Status	Error Message	説明
400	Failed to update identity	更新操作がデータを変更しなかった（変更が検出されなかった）
401	token could not be verified	認証トークンが欠落しているか無効
403	User is not authorized to access this resource	リクエストされた操作に対する権限が不足している
404	Identity not found	GET/PATCH/DELETE操作に対してアイデンティティが存在しない
500	Failed to get identity	取得中のデータベース接続の問題または予期しない失敗
500	Failed to find identities	リスト取得中のデータベース接続の問題、無効なフィルタ構文、または予期しない失敗
500	Failed to update identity	更新中のデータベース接続の問題または予期しない失敗
500	Failed to delete identity	削除中のデータベース接続の問題または予期しない失敗

エラーレスポンス形式

{
  "error": {
    "message": "エラーメッセージの説明",
    "data": ["追加のエラー詳細"]
  }
}

🔗 関連ドキュメント

Error Handling - エラーパターンの理解
Schema Component - データバリデーションの概念
Custom Service Tutorial - 独自のサービスを構築
User Service - ユーザー管理操作

🚀 クイックスタート​

📋 エンドポイント概要​

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

フィールド詳細​

🔐 認証ヘッダー​

🔧 APIエンドポイント​

1. IDでアイデンティティを取得​

2. アイデンティティのリスト取得​

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

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

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

6. アイデンティティのアンロック​

⚙️ 設定オプション​

サービス設定​

設定詳細​

🔐 セキュリティ設定​

👥 ユーザータイプ設定​

設定例​

🚨 エラーハンドリング​

一般的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

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

フィールド詳細

🔐 認証ヘッダー

🔧 APIエンドポイント

1. IDでアイデンティティを取得

2. アイデンティティのリスト取得

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

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

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

6. アイデンティティのアンロック

⚙️ 設定オプション

サービス設定

設定詳細

🔐 セキュリティ設定

👥 ユーザータイプ設定

設定例

🚨 エラーハンドリング

一般的なエラーコード

エラーレスポンス形式

🔗 関連ドキュメント