# 機能設計書 77-セキュア入力

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるセキュア入力機能の設計について記載する。この機能はmacOSのSecure Input APIを利用して、パスワード入力時など機密性の高い入力中にキーロガーなどの悪意あるソフトウェアからキーストロークを保護する。

### 本機能の処理概要

**業務上の目的・背景**：
macOSには、キーロガーなどの悪意あるアプリケーションがキーストロークを傍受することを防ぐためのSecure Input APIが存在する。SSHパスワード、sudoパスワード、その他の機密情報を入力する際に、この機能を有効にすることでセキュリティを向上させることができる。Ghosttyはこの機能を自動的にまたは手動でトグルする手段を提供する。

**機能の利用シーン**：
- SSHでリモートサーバーにログインする際のパスワード入力
- sudoコマンド実行時のパスワード入力
- シェル統合によるパスワードプロンプト検出時の自動有効化
- ユーザーによる手動でのセキュア入力モード切り替え

**主要な処理内容**：
1. `toggle_secure_input`アクションの受付
2. macOS Secure Input APIの呼び出し
3. セキュア入力状態の視覚的インジケーター表示
4. シェル統合による自動トリガー（パスワード入力検出）

**関連システム・外部連携**：
- macOS Secure Input API（EnableSecureEventInput / DisableSecureEventInput）
- シェル統合（パスワードプロンプト検出）

**権限による制御**：
- macOSでのみ利用可能
- システムレベルのAPI呼び出しのため特別な権限は不要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | セキュア入力状態の表示、トグル操作 |
| 15 | セキュア入力オーバーレイ | 主画面 | セキュア入力モードの視覚的インジケーター |

## 機能種別

セキュリティ / システムAPI連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | toggle操作（パラメータなし） | - |

### 入力データソース

- キーバインド`toggle_secure_input`アクション
- シェル統合からのパスワード入力検出通知

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| secure_input | SecureInput | on/off/toggle状態 |

### 出力先

- macOS Secure Input API
- 視覚的インジケーター（オーバーレイ）

## 処理フロー

### 処理シーケンス

```
1. セキュア入力トリガー
   └─ キーバインド or シェル統合パスワード検出
2. Surface.notifyPasswordInput（シェル統合の場合）
   └─ password_inputメッセージを送信
3. secure_inputアクション発行
   └─ apprへ転送
4. macOS Secure Input API呼び出し
   └─ EnableSecureEventInput / DisableSecureEventInput
5. 視覚的インジケーター更新
   └─ セキュア入力オーバーレイの表示/非表示
```

### フローチャート

```mermaid
flowchart TD
    A{トリガー種別} -->|キーバインド| B[toggle_secure_input アクション]
    A -->|シェル統合| C[password_input メッセージ]
    B --> D[secure_input アクション .toggle]
    C --> E[notifyPasswordInput]
    E --> F[secure_input アクション on/off]
    D --> G{プラットフォーム?}
    F --> G
    G -->|macOS| H[Secure Input API 呼び出し]
    G -->|その他| I[何もしない]
    H --> J{成功?}
    J -->|Yes| K[視覚インジケーター更新]
    J -->|No| L[エラーログ]
    K --> M[終了]
    L --> M
    I --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-77-1 | macOS専用 | セキュア入力はmacOSでのみ有効 | macOS |
| BR-77-2 | 手動アンロック | 自動で有効になった場合も手動で無効化が必要な場合がある | 常時 |
| BR-77-3 | アプリ終了時解除 | Ghostty終了時はセキュア入力が自動解除される | 常時 |
| BR-77-4 | 視覚的通知 | セキュア入力中はユーザーに明示的に通知する | 常時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非macOS | macOS以外で実行 | 何もしない |
| - | API失敗 | Secure Input APIエラー | エラーログ出力 |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- Secure Input API呼び出しは即座に完了
- 視覚的インジケーターの更新は非同期

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

- Secure Inputはシステムレベルでキーストロークを保護
- 他のアプリケーション（1Password、Karabiner等）のSecure Input状態との競合に注意
- セキュア入力中は他のアプリケーションのキーボードショートカットが機能しない場合がある

## 備考

- macOSのSecure Input APIはプロセス単位で動作
- シェル統合が有効な場合、パスワードプロンプトを自動検出して有効化可能
- メニューバーにセキュア入力状態を表示するオプションあり

---

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

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

### 推奨読解順序

#### Step 1: アクション定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Binding.zig | `src/input/Binding.zig` | toggle_secure_inputアクション定義（727行目） |
| 1-2 | action.zig | `src/apprt/action.zig` | secure_inputアクション（246-251行目） |

**読解のコツ**: `toggle_secure_input`はキーバインドアクション、`secure_input`はapprへのアクション。SecureInput enumはon/off/toggleの3状態。

#### Step 2: Surfaceでの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | performBindingAction内の処理（5726-5730行目） |
| 2-2 | Surface.zig | `src/Surface.zig` | notifyPasswordInput関数（1371-1377行目付近） |

**主要処理フロー**:
1. **5726-5730行目**: `toggle_secure_input` -> `secure_input`アクション発行
2. **1371-1377行目**: パスワード入力検出時の処理

#### Step 3: macOS実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | menuSecureInput, Secure Input関連処理 |

**主要処理フロー**:
- EnableSecureEventInput() / DisableSecureEventInput() API呼び出し

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

```
toggle_secure_input キーバインド
    │
    └─ Surface.performBindingAction
           │
           └─ rt_app.performAction(.secure_input, .toggle)
                  │
                  └─ macOS AppDelegate
                         │
                         └─ EnableSecureEventInput() / DisableSecureEventInput()

シェル統合 パスワード検出
    │
    └─ password_input メッセージ
           │
           └─ Surface.notifyPasswordInput
                  │
                  └─ rt_app.performAction(.secure_input, on/off)
```

### データフロー図

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

キーバインド ───▶ toggle_secure_input
                        │
                        ▼
               secure_input アクション
                        │
                        ▼
                  {プラットフォーム判定}
                        │
              ┌─────────┴─────────┐
              │                   │
           [macOS]             [その他]
              │                   │
              ▼                   ▼
    Secure Input API          何もしない
              │
              ▼
    視覚インジケーター
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Binding.zig | `src/input/Binding.zig` | ソース | toggle_secure_inputアクション定義 |
| action.zig | `src/apprt/action.zig` | ソース | secure_inputアクション定義 |
| Surface.zig | `src/Surface.zig` | ソース | アクション処理、notifyPasswordInput |
| AppDelegate.swift | `macos/Sources/App/macOS/AppDelegate.swift` | ソース | macOS Secure Input実装 |
| command.zig | `src/input/command.zig` | ソース | コマンドパレット定義（636-640行目） |
| command_palette.zig | `src/apprt/gtk/class/command_palette.zig` | ソース | GTK非対応フィルタ（213行目） |
