# 機能設計書 152-SecureRandom\int

## 概要

本ドキュメントは、Hack Standard Library (HSL) における `SecureRandom\int` 関数の機能設計を記載する。この関数は暗号学的に安全なランダム整数を生成する機能を提供する。

### 本機能の処理概要

`SecureRandom\int` は、暗号学的に安全な方法で指定された範囲内のランダムな整数を生成する関数である。内部的には `_Private\Native\random_int` ネイティブ関数を呼び出し、オペレーティングシステムが提供する暗号学的に安全なランダムソースからエントロピーを取得する。

**業務上の目的・背景**：暗号学的に安全な整数乱数は、セキュリティが重要なアプリケーションにおいて広く必要とされる。具体的には、セッションID生成、CSRF トークン生成、パスワードソルト生成、暗号化キー導出、セキュアなシャッフル処理などで使用される。通常の擬似乱数生成器（PRNG）は決定論的であり、内部状態が判明すると将来の出力が予測可能になるため、セキュリティクリティカルな場面では CSPRNG（暗号学的擬似乱数生成器）を使用する必要がある。

**機能の利用シーン**：
- セッションIDやトークンの生成
- 暗号化処理における乱数要素の生成
- セキュアなランダム選択（配列からのセキュアな要素選択）
- ワンタイムパスワード（OTP）の数字生成
- セキュアなデータのシャッフル処理

**主要な処理内容**：
1. 入力パラメータ `$min` と `$max` の検証（$min <= $max）
2. `_Private\Native\random_int` ネイティブ関数の呼び出し
3. OS の暗号学的ランダムソースから指定範囲内の整数を取得
4. 結果を返却

**関連システム・外部連携**：Hack ランタイムの `_Private\Native\random_int` を使用し、オペレーティングシステムが提供する暗号学的に安全なランダムソース（Linux では `/dev/urandom` または `getrandom()`、Windows では `CryptGenRandom` または BCryptGenRandom）からエントロピーを取得する。

**権限による制御**：本機能は純粋関数として実装されており、特別な権限は必要としない。`[leak_safe]` コンテキストで実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはUIを持たないライブラリのため画面なし |

## 機能種別

計算処理（乱数生成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $min | int | No | 生成する乱数の最小値。デフォルトは PHP_INT_MIN | $min <= $max でなければならない |
| $max | int | No | 生成する乱数の最大値。デフォルトは PHP_INT_MAX | $min <= $max でなければならない |

### 入力データソース

オペレーティングシステムの暗号学的に安全なランダムソース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | [$min, $max] の範囲内の暗号学的に安全なランダム整数。$min 以上 $max 以下の値を返す（両端を含む） |

### 出力先

関数の戻り値として呼び出し元に返却

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ invariant() で $min <= $max をチェック
   └─ 違反時は InvariantException をスロー
2. ネイティブ関数の呼び出し
   └─ _Private\Native\random_int($min, $max) を呼び出し
3. 結果の返却
   └─ OS から取得したセキュアな乱数を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{$min <= $max?}
    B -->|No| C[InvariantException をスロー]
    B -->|Yes| D[_Private\Native\random_int 呼び出し]
    D --> E[OS暗号化ランダムソースから乱数取得]
    E --> F[結果を返却]
    F --> G[終了]
    C --> H[異常終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-152-01 | 範囲制約 | 戻り値は必ず [$min, $max] の範囲内となる（両端を含む） | 常時 |
| BR-152-02 | 入力検証 | $min は $max 以下でなければならない | 常時 |
| BR-152-03 | 暗号学的安全性 | 生成される値は暗号学的に安全でなければならない | 常時 |
| BR-152-04 | 一様分布 | 範囲内の全ての整数が等確率で選択される | 常時 |

### 計算ロジック

```
// 入力検証
invariant($min <= $max, 'Expected $min (%d) to be less than or equal to $max (%d).', $min, $max);

// ネイティブ関数呼び出し
result = _Private\Native\random_int($min, $max)
```

範囲が非常に広い場合（例：PHP_INT_MIN から PHP_INT_MAX）でも、一様分布が保証される。これはネイティブ実装がリジェクションサンプリングなどの技術を使用しているため。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベース操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $min > $max の場合 | 呼び出し側で適切な $min, $max を指定する |

### リトライ仕様

リトライ処理は不要。入力パラメータが正しければ、OSレベルのランダムソースへのアクセスは常に成功することが期待される。

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

本機能はトランザクションを使用しない純粋関数である。

## パフォーマンス要件

- 単一呼び出しのレイテンシ：マイクロ秒オーダー
- スループット：システムのランダムソースに依存するが、一般的に高スループット
- 範囲のサイズによるパフォーマンス影響：実質的になし

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

- 生成される値は暗号学的に安全なランダムソースから導出される
- 予測不可能性が保証されている
- `[leak_safe]` コンテキストで実行可能であり、副作用がない
- セキュリティクリティカルな用途に使用可能
- 内部状態の露出による将来の出力の予測は不可能

## 備考

- 非暗号用途（ゲームのランダム要素など）では、パフォーマンスの観点から `PseudoRandom\int` の使用を検討すること
- デフォルト引数により、PHP_INT_MIN から PHP_INT_MAX の全範囲での乱数生成が可能
- `SecureRandom\float` は本関数を内部で使用している

---

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

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

### 推奨読解順序

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

本機能は単純な整数型のみを扱うため、特別なデータ構造は存在しない。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| - | - | - | 特別なデータ構造なし |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | secure.php | `src/random/secure.php` | SecureRandom\int 関数の実装（31-42行目） |

**主要処理フロー**:
1. **31-34行目**: 関数宣言。$min と $max のデフォルト値は PHP_INT_MIN と PHP_INT_MAX
2. **35-40行目**: invariant による入力検証。$min が $max より大きい場合は例外をスロー
3. **41行目**: `_Private\Native\random_int($min, $max)` を呼び出して結果を返却

```hack
function int(
  int $min = \PHP_INT_MIN,
  int $max = \PHP_INT_MAX,
)[leak_safe]: int {
  invariant(
    $min <= $max,
    'Expected $min (%d) to be less than or equal to $max (%d).',
    $min,
    $max,
  );
  return _Private\Native\random_int($min, $max);
}
```

#### Step 3: ネイティブ実装への接続を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | - | Hack Runtime | `_Private\Native\random_int` はHackランタイムのネイティブ関数。OSの暗号化ランダムソースを使用 |

**読解のコツ**: `_Private\Native\random_int` は Hack ランタイムに組み込まれたネイティブ関数であり、Hack コード内では定義されていない。この関数はオペレーティングシステムが提供する暗号学的に安全なランダムソースにアクセスする。

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

```
SecureRandom\int($min, $max)
    │
    ├─ invariant() [入力検証]
    │
    └─ _Private\Native\random_int($min, $max)
           │
           └─ [OS暗号化ランダムソース]
               ├─ Linux: /dev/urandom or getrandom()
               └─ Windows: CryptGenRandom or BCryptGenRandom
```

### データフロー図

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

$min (int) ─────────▶┐
                     ├──▶ invariant() ──▶ 検証OK ──▶ _Private\Native\random_int()
$max (int) ─────────▶┘                                      │
                                                            ▼
                                                 [$min, $max] 範囲の整数 ──▶ int
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| secure.php | `src/random/secure.php` | ソース | SecureRandom 名前空間の公開関数を定義 |
| SecureRandomTest.php | `tests/random/SecureRandomTest.php` | テスト | SecureRandom 関数群のユニットテスト |
| RandomTestTrait.php | `tests/random/RandomTestTrait.php` | テスト | ランダム関数の共通テストトレイト。testIntRange() と testIntException() を含む |
