# 機能設計書 61-認証検証

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける認証検証機能の設計を記述する。JWTトークンの検証や認証状態の確認を行う機能について詳細に解説する。

### 本機能の処理概要

**業務上の目的・背景**：ECサイトの管理画面やAPIへのアクセスにおいて、ユーザーが正当な権限を持っているかを確認することは、セキュリティ上極めて重要である。認証検証機能は、JWTトークンを使用してユーザーの認証状態を検証し、不正アクセスを防止する。これにより、管理者や顧客のデータが保護され、安全なコマース運営が可能となる。

**機能の利用シーン**：
- 管理画面へのログイン後、各API呼び出し時のトークン検証
- 外部認証プロバイダー（OAuth）からのコールバック時の認証情報検証
- パスワードリセットやプロバイダー情報更新時のトークン検証
- セッション維持のためのトークンリフレッシュ時の検証

**主要な処理内容**：
1. HTTPリクエストヘッダーからAuthorizationトークンを抽出
2. JWTトークンのデコードと署名検証
3. トークンに含まれるactor_type（user/customer）の検証
4. ProviderIdentityテーブルからエンティティIDに紐づく認証情報を取得
5. 認証コンテキスト（auth_context）をリクエストオブジェクトに付与

**関連システム・外部連携**：
- 外部認証プロバイダー（Google、GitHub等のOAuthプロバイダー）
- キャッシュモジュール（OAuth状態管理用）

**権限による制御**：actor_type（user/customer）によってアクセス可能なリソースが異なる。userはAdmin APIへ、customerはStore APIへのアクセスが許可される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ログイン画面 | 主画面 | ログイントークンの検証 |
| 2 | パスワードリセット画面 | 参照画面 | リセットトークンの検証 |

## 機能種別

認証・検証処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Authorization | string | Yes | HTTPヘッダーのBearerトークン | Bearer形式であること |
| actor_type | string | Yes | アクターの種別（user/customer） | 有効なアクタータイプであること |
| auth_provider | string | Yes | 認証プロバイダー名 | 登録済みプロバイダーであること |

### 入力データソース

- HTTPリクエストヘッダー（Authorization）
- URLパラメータ（actor_type、auth_provider）
- ConfigModule（JWT秘密鍵、検証オプション）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| auth_identity_id | string | 認証アイデンティティID |
| actor_id | string | アクターID（ユーザーID or 顧客ID） |
| actor_type | string | アクタータイプ（user/customer） |
| app_metadata | object | アプリケーションメタデータ |
| user_metadata | object | ユーザーメタデータ |

### 出力先

- リクエストオブジェクト（req.auth_context）

## 処理フロー

### 処理シーケンス

```
1. トークン抽出
   └─ HTTPヘッダーからAuthorizationトークンを取得
2. トークンデコード
   └─ getAuthContextFromJwtTokenでJWTをデコード・検証
3. エンティティID検証
   └─ トークンからentity_idを抽出し、存在確認
4. プロバイダー情報取得
   └─ AuthModuleでProviderIdentityを検索
5. 認証コンテキスト設定
   └─ req.auth_contextに認証情報を付与
6. 次処理へ
   └─ next()でミドルウェアチェーン継続
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B[Authorizationヘッダー取得]
    B --> C{トークンあり?}
    C -->|No| D[401 Unauthorized]
    C -->|Yes| E[JWTデコード・検証]
    E --> F{トークン有効?}
    F -->|No| D
    F -->|Yes| G[entity_id抽出]
    G --> H[ProviderIdentity検索]
    H --> I{存在する?}
    I -->|No| D
    I -->|Yes| J[auth_context設定]
    J --> K[next: 次処理へ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-61-01 | トークン必須 | APIアクセスにはBearerトークンが必須 | 認証が必要なエンドポイント |
| BR-61-02 | アクタータイプ検証 | トークンのactor_typeとリクエストのactor_typeが一致すること | 全認証リクエスト |
| BR-61-03 | プロバイダー検証 | トークンのproviderが有効なプロバイダーであること | プロバイダー更新時 |

### 計算ロジック

特になし

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トークン検証 | provider_identity | SELECT | entity_idとproviderでプロバイダー情報を取得 |
| 認証情報取得 | auth_identity | SELECT | auth_identity_idで認証アイデンティティを取得 |

### テーブル別操作詳細

#### provider_identity

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | entity_id, provider | WHERE entity_id = ? AND provider = ? | 複合インデックス使用 |
| SELECT | provider_metadata, user_metadata | 取得対象 | 認証コンテキスト構築用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UNAUTHORIZED | MedusaError | トークンがない、または無効 | 401レスポンス返却 |
| NOT_FOUND | MedusaError | entity_idに対応するProviderIdentityが存在しない | 401レスポンス返却 |
| INVALID_DATA | MedusaError | 複数のAuthIdentityが見つかった | 500エラー（データ不整合） |

### リトライ仕様

認証検証処理においてリトライは行わない。失敗時は即座にエラーレスポンスを返却する。

## トランザクション仕様

認証検証はSELECT操作のみのため、トランザクション管理は不要。

## パフォーマンス要件

- トークン検証処理は100ms以内に完了すること
- provider_identityテーブルの(entity_id, provider)にユニークインデックスが設定されている

## セキュリティ考慮事項

- JWTトークンは署名検証により改ざんを検知
- トークンの有効期限を設定し、長期間の不正利用を防止
- 秘密鍵はConfigModuleで管理し、環境変数から取得
- OAuth状態管理にはキャッシュモジュールを使用し、20分の有効期限を設定

## 備考

- JWT検証オプションはjwtOptionsまたはjwt_verify_optionsで設定可能
- 公開鍵方式（jwtPublicKey）にも対応

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

JWTトークンのペイロード構造と、認証コンテキストの型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | auth-identity.ts | `packages/modules/auth/src/models/auth-identity.ts` | AuthIdentityモデルの構造（id, provider_identities, app_metadata） |
| 1-2 | provider-identity.ts | `packages/modules/auth/src/models/provider-identity.ts` | ProviderIdentityモデルの構造（entity_id, provider, user_metadata, provider_metadata） |

**読解のコツ**: MedusaのモデルはDDD形式で定義されている。`model.define`で定義されたエンティティは、MikroORMによりテーブルにマッピングされる。

#### Step 2: エントリーポイントを理解する

トークン検証ミドルウェアの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | validate-token.ts | `packages/medusa/src/api/auth/utils/validate-token.ts` | トークン検証ミドルウェアの全体フロー |

**主要処理フロー**:
1. **23-28行目**: validateToken関数の定義、Express middlewareパターン
2. **37-44行目**: getAuthContextFromJwtTokenによるJWTデコード・検証
3. **55-74行目**: AuthModuleでProviderIdentityを検索
4. **80-86行目**: auth_contextをリクエストに設定

#### Step 3: サービス層を理解する

AuthModuleServiceの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | auth-module.ts | `packages/modules/auth/src/services/auth-module.ts` | AuthModuleServiceの実装 |

**主要処理フロー**:
- **227-240行目**: authenticate関数 - 認証処理の実行
- **242-255行目**: validateCallback関数 - OAuthコールバック検証
- **257-406行目**: getAuthIdentityProviderService関数 - プロバイダーサービスの取得

### プログラム呼び出し階層図

```
validateToken (middleware)
    │
    ├─ getAuthContextFromJwtToken
    │      └─ jwt.verify (jsonwebtoken)
    │
    └─ authModule.listProviderIdentities
           └─ providerIdentityService_.list
                  └─ BaseRepository.list
```

### データフロー図

```
[入力]                          [処理]                              [出力]

Authorization Header ───▶ validateToken Middleware ───▶ req.auth_context
(Bearer token)                     │                        ├─ actor_type
                                   │                        ├─ auth_identity_id
                                   ▼                        ├─ actor_id
                          getAuthContextFromJwtToken        ├─ app_metadata
                                   │                        └─ user_metadata
                                   ▼
                          authModule.listProviderIdentities
                                   │
                                   ▼
                           provider_identity table
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| validate-token.ts | `packages/medusa/src/api/auth/utils/validate-token.ts` | ソース | トークン検証ミドルウェア |
| auth-module.ts | `packages/modules/auth/src/services/auth-module.ts` | ソース | 認証モジュールサービス |
| auth-identity.ts | `packages/modules/auth/src/models/auth-identity.ts` | ソース | 認証アイデンティティモデル |
| provider-identity.ts | `packages/modules/auth/src/models/provider-identity.ts` | ソース | プロバイダーアイデンティティモデル |
| auth-provider.ts | `packages/modules/auth/src/services/auth-provider.ts` | ソース | 認証プロバイダーサービス |
