# 機能設計書 56-CORS設定

## 概要

本ドキュメントは、Actual Budget同期サーバーにおけるCORS（Cross-Origin Resource Sharing）設定機能の設計を記述する。この機能は、異なるオリジンからのAPIリクエストを適切に制御し、Webブラウザベースのクライアントからの安全なアクセスを可能にする。

### 本機能の処理概要

Actual Budget同期サーバーにおいて、Webブラウザからのクロスオリジンリクエストを許可するためのCORS設定を提供する機能である。corsミドルウェアを使用し、プリフライトリクエスト（OPTIONS）への応答およびCORS関連ヘッダーの付与を行う。

**業務上の目的・背景**：Actual BudgetはWebアプリケーションとしても動作するため、同期サーバーとは異なるオリジン（ドメイン、ポート）からのAPIアクセスが発生する。CORSを適切に設定することで、Webブラウザのセキュリティポリシーに準拠しながら、正当なクライアントからのアクセスを許可する。

**機能の利用シーン**：
- Webブラウザからの同期API呼び出し
- 開発環境でのlocalhostからのアクセス
- プラグインからの外部API呼び出し（CORSプロキシ機能）

**主要な処理内容**：
1. Access-Control-Allow-Originヘッダーの設定
2. Access-Control-Allow-Methodsヘッダーの設定
3. Access-Control-Allow-Headersヘッダーの設定
4. プリフライトリクエスト（OPTIONS）への応答
5. CORSプロキシによる外部API中継（オプション）

**関連システム・外部連携**：Webブラウザ、外部API（CORSプロキシ経由）

**権限による制御**：CORSプロキシ機能は設定で有効/無効を切り替え可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし | - | バックエンド機能のため直接関連する画面なし |

## 機能種別

サーバー機能 / セキュリティ設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Origin | string | No | リクエスト元オリジン | HTTPヘッダーから自動取得 |

### 入力データソース

HTTPリクエストヘッダー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Access-Control-Allow-Origin | string | 許可されるオリジン（* または特定オリジン） |
| Access-Control-Allow-Methods | string | 許可されるHTTPメソッド |
| Access-Control-Allow-Headers | string | 許可されるリクエストヘッダー |
| Access-Control-Allow-Credentials | boolean | 認証情報の送信許可 |

### 出力先

HTTPレスポンスヘッダー

## 処理フロー

### 処理シーケンス

```
1. HTTPリクエスト受信
   └─ Expressミドルウェアチェーン

2. CORSミドルウェア処理
   ├─ Originヘッダーチェック
   └─ CORSヘッダー付与

3. プリフライト処理（OPTIONSリクエストの場合）
   └─ 200 OKで即座にレスポンス

4. 通常リクエスト処理
   └─ 次のミドルウェアへ
```

### フローチャート

```mermaid
flowchart TD
    A[HTTPリクエスト受信] --> B{OPTIONSリクエスト?}
    B -->|Yes| C[プリフライト応答]
    C --> D[CORSヘッダー付与]
    D --> E[200 OK レスポンス]
    B -->|No| F[CORSヘッダー付与]
    F --> G[次のミドルウェアへ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-1 | 全オリジン許可 | デフォルトですべてのオリジンを許可（*） | 常時 |
| BR-56-2 | プリフライト自動応答 | OPTIONSリクエストに自動応答 | OPTIONSリクエスト時 |
| BR-56-3 | CORSプロキシ | 設定で有効化した場合のみCORSプロキシエンドポイントを提供 | corsProxy.enabled=true時 |

### 計算ロジック

特になし

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

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

この機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | CORSエラー | ブラウザ側で発生 | サーバー設定を確認 |

### リトライ仕様

この機能にリトライロジックはない。

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

トランザクション処理なし

## パフォーマンス要件

- CORSヘッダー処理：1ms未満
- プリフライト応答：10ms以内

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

- 本番環境では特定オリジンのみ許可することを推奨
- CORSプロキシは慎重に有効化（任意の外部URLへのアクセスを可能にする）
- 認証情報を含むリクエストでは * の使用は避ける

## 備考

- corsパッケージを使用
- CORSプロキシ機能はプラグイン向け

---

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

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

### 推奨読解順序

#### Step 1: CORSミドルウェア設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | app.ts | `packages/sync-server/src/app.ts` | CORSミドルウェアの設定 |

**読解のコツ**: corsパッケージのオプション仕様を理解しておくと、設定の意味が把握しやすい。

**主要処理フロー**:
- **5行目**: cors インポート
- **28行目**: app.use(cors()) でCORSミドルウェア適用

#### Step 2: Cross-Origin-Embedder-Policy設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | app.ts | `packages/sync-server/src/app.ts` | COEP/COOP設定 |

**主要処理フロー**:
- **128-132行目**: Cross-Origin-Opener-Policy設定
- **129行目**: same-originポリシー
- **130行目**: require-corpポリシー

#### Step 3: CORSプロキシ機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | app.ts | `packages/sync-server/src/app.ts` | CORSプロキシルーター設定 |
| 3-2 | load-config.js | `packages/sync-server/src/load-config.js` | CORSプロキシ設定 |

**主要処理フロー**:
- **64-66行目**: corsProxy.enabledの場合のみルーターをマウント
- **291-300行目**（load-config.js）: corsProxy設定スキーマ

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

```
HTTPリクエスト
    │
    └─ Express ミドルウェアチェーン
           │
           ├─ cors() ミドルウェア
           │      │
           │      ├─ Originヘッダー確認
           │      ├─ CORSヘッダー付与
           │      └─ (OPTIONSなら) プリフライト応答
           │
           ├─ COEP/COOP ミドルウェア
           │      └─ セキュリティヘッダー付与
           │
           └─ 次のミドルウェア/ルートハンドラ
```

### データフロー図

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

クライアント ───▶ Express Server
     │                    │
     ▼                    ▼
Originヘッダー      corsミドルウェア
                          │
                    ┌─────┴─────┐
                    ▼           ▼
              [OPTIONS]    [その他]
                    │           │
                    ▼           ▼
             プリフライト    CORSヘッダー付与
             応答生成              │
                    │           ▼
                    ▼      次のミドルウェアへ
              200 OK
              + CORSヘッダー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| app.ts | `packages/sync-server/src/app.ts` | ソース | CORSミドルウェア設定 |
| load-config.js | `packages/sync-server/src/load-config.js` | ソース | CORSプロキシ設定 |
| app-cors-proxy.js | `packages/sync-server/src/app-cors-proxy.js` | ソース | CORSプロキシ実装 |
