# 機能設計書 57-HTTPS対応

## 概要

本ドキュメントは、Actual Budget同期サーバーにおけるHTTPS対応機能の設計を記述する。この機能は、SSL/TLS暗号化通信をサポートし、クライアントとサーバー間の通信を保護する。

### 本機能の処理概要

Actual Budget同期サーバーにおいて、SSL/TLS証明書を使用したHTTPS通信を提供する機能である。Node.jsのhttpsモジュールを使用し、設定された証明書と秘密鍵でHTTPSサーバーを起動する。

**業務上の目的・背景**：予算データや認証情報といった機密性の高いデータがネットワーク上を流れるため、通信の暗号化は必須のセキュリティ要件である。HTTPSを有効にすることで、中間者攻撃（MITM）や盗聴からデータを保護する。

**機能の利用シーン**：
- 本番環境でのセキュアな通信
- インターネット経由でのサーバーアクセス
- 自己署名証明書を使用した開発環境

**主要な処理内容**：
1. HTTPS設定（証明書、秘密鍵）の読み込み
2. HTTPSサーバーの起動
3. SSL/TLS暗号化通信の提供
4. HTTP（非暗号化）との切り替え

**関連システム・外部連携**：SSL/TLS証明書発行機関（Let's Encrypt等）

**権限による制御**：HTTPS設定の変更はサーバー管理者のみ

## 関連画面

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

## 機能種別

サーバー機能 / セキュリティ・暗号化

## 入力仕様

### 入力パラメータ（設定）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| https.key | string | Yes（HTTPS時） | 秘密鍵（PEM形式またはファイルパス） | - |
| https.cert | string | Yes（HTTPS時） | 証明書（PEM形式またはファイルパス） | - |

### 入力データソース

- 環境変数（ACTUAL_HTTPS_KEY、ACTUAL_HTTPS_CERT）
- 設定ファイル（config.json）

## 出力仕様

### 出力データ

なし（サーバー起動のみ）

### 出力先

なし

## 処理フロー

### 処理シーケンス

```
1. サーバー起動処理
   └─ run()関数実行

2. HTTPS設定確認
   ├─ https.keyの存在チェック
   └─ https.certの存在チェック

3. 設定値の解析
   ├─ PEM形式の場合: そのまま使用
   └─ ファイルパスの場合: ファイル読み込み

4. サーバー起動
   ├─ HTTPS設定あり: https.createServer()
   └─ HTTPS設定なし: app.listen()
```

### フローチャート

```mermaid
flowchart TD
    A[run()関数開始] --> B{https.key設定あり?}
    B -->|No| C[HTTP サーバー起動]
    B -->|Yes| D{https.cert設定あり?}
    D -->|No| C
    D -->|Yes| E[証明書設定解析]
    E --> F{PEM形式?}
    F -->|Yes| G[そのまま使用]
    F -->|No| H[ファイル読み込み]
    G --> I[HTTPS サーバー起動]
    H --> I
    C --> J[サーバー起動完了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-1 | 設定両方必須 | keyとcertの両方が設定されている場合のみHTTPSを有効化 | サーバー起動時 |
| BR-57-2 | PEMまたはパス | 設定値がPEM形式（-----BEGIN で開始）の場合はそのまま使用、それ以外はファイルパスとして読み込み | 設定解析時 |
| BR-57-3 | フォールバック | HTTPS設定がない場合はHTTPで起動 | サーバー起動時 |

### 計算ロジック

特になし

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル読み込みエラー | 証明書/秘密鍵ファイルが見つからない | パス設定を確認 |
| - | 証明書エラー | 無効な証明書形式 | 証明書を再生成 |
| - | 鍵ペアエラー | 秘密鍵と証明書が一致しない | 正しいペアを使用 |

### リトライ仕様

この機能にリトライロジックはない。エラー時はサーバー起動失敗。

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

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

## パフォーマンス要件

- TLSハンドシェイク：100ms以内（ネットワーク状況依存）
- 暗号化オーバーヘッド：5%未満

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

- 秘密鍵ファイルのアクセス権限を適切に設定（600推奨）
- 本番環境では信頼できる認証局から発行された証明書を使用
- TLS 1.2以上を推奨
- 定期的な証明書更新

## 備考

- Let's Encryptなどの無料証明書が利用可能
- 自己署名証明書は開発/テスト環境のみで使用

---

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

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

### 推奨読解順序

#### Step 1: 設定スキーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | load-config.js | `packages/sync-server/src/load-config.js` | HTTPS設定スキーマ |

**読解のコツ**: convictライブラリの設定スキーマ定義パターンを理解しておくと、設定の意味が把握しやすい。

**主要処理フロー**:
- **154-170行目**: https設定スキーマ
- **157-161行目**: https.key設定
- **163-168行目**: https.cert設定

#### Step 2: 設定値の解析処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | app.ts | `packages/sync-server/src/app.ts` | parseHTTPSConfig関数 |

**主要処理フロー**:
- **157-162行目**: parseHTTPSConfig関数
- **158-159行目**: PEM形式の判定（-----BEGIN で開始）
- **161行目**: ファイルパスの場合はfs.readFileSync

#### Step 3: サーバー起動処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | app.ts | `packages/sync-server/src/app.ts` | run関数のHTTPS分岐 |

**主要処理フロー**:
- **174行目**: run関数開始
- **196行目**: https.keyとhttps.certの存在チェック
- **197行目**: httpsモジュールの動的インポート
- **198-202行目**: httpsOptions構築
- **203-205行目**: https.createServerでHTTPSサーバー起動
- **206-209行目**: HTTPフォールバック

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

```
run()
    │
    ├─ config.get('https.key')
    ├─ config.get('https.cert')
    │
    ├─ [HTTPS設定あり]
    │      │
    │      ├─ import('node:https')
    │      │
    │      ├─ parseHTTPSConfig(key)
    │      │      └─ fs.readFileSync() [パスの場合]
    │      │
    │      ├─ parseHTTPSConfig(cert)
    │      │      └─ fs.readFileSync() [パスの場合]
    │      │
    │      └─ https.createServer(httpsOptions, app)
    │             └─ .listen(port, hostname)
    │
    └─ [HTTPS設定なし]
           └─ app.listen(port, hostname)
```

### データフロー図

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

環境変数 ─────────▶ convict設定 ─────────▶ config.get()
ACTUAL_HTTPS_KEY            │
ACTUAL_HTTPS_CERT           ▼
                    parseHTTPSConfig()
                            │
        ┌───────────────────┴───────────────────┐
        ▼                                       ▼
  [PEM形式]                               [ファイルパス]
  そのまま使用                            fs.readFileSync()
        │                                       │
        └──────────────┬────────────────────────┘
                       ▼
                https.createServer()
                       │
                       ▼
                  HTTPS サーバー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| app.ts | `packages/sync-server/src/app.ts` | ソース | HTTPS サーバー起動処理 |
| load-config.js | `packages/sync-server/src/load-config.js` | ソース | HTTPS 設定スキーマ |
