lazarv · lazarv · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026
@@ -0,0 +1,145 @@
+---
+title: サーバ関数の暗号化
+category: Features
+order: 3
+---
+
+import Link from "../../../../components/Link.jsx";
+
+# サーバ関数の暗号化
+
+`@lazarv/react-server`はデフォルトですべてのサーバー関数識別子を**AES-256-GCM**を使用して暗号化します。これにより、レンダリング時に明示的に公開されていないサーバ関数をクライアントが発見したり呼び出したりすることを防止します。
+
+暗号化を行わない場合、サーバー関数識別子は平文の文字列であり、ソースファイルのパスや関数名（例: `src/actions#deleteUser`）を露呈します。これにより、クライアントは任意のリクエストを作成し、アプリケーション内のあらゆるサーバ関数を呼び出すことが可能になります。これは、そのユーザーに対してレンダリングされたことのない関数であっても同様です。暗号化により、レンダリング時にサーバーから返されたサーバ関数のみが呼び出し可能となります。
+
+<Link name="how-it-works">
+## 仕組み
+</Link>
+
+サーバ関数トークンは2つのタイプがあります。
+
+**インライントークン**は、サーバ関数参照が初めて使用された際に生成されます。暗号化されたトークンは関数インスタンスにキャッシュされ、Reactの内部フォーム状態マッチング（例：`useActionState`）が正しく動作するようにします。インラインサーバ関数およびクライアントコンポーネントにプロップとして渡されるサーバ関数は、RSCストリームに埋め込まれたこれらのトークンを使用します。
+
+**静的トークン**は、ビルド時（または開発時のVite変換時）にサーバ関数モジュール（最上位に`"use server"`を含むファイル）に対して生成されます。これらのトークンはクライアント用JavaScriptバンドルに埋め込まれ、クライアントコンポーネントがサーバ関数を直接インポートする際に使用されます。
+
+両方のタイプは同じ鍵で暗号化され、サーバ関数が呼び出された際にサーバー上で透過的に復号化されます。
+
+<Link name="zero-configuration">
+## ゼロコンフィグ
+</Link>
+
+暗号化は設定不要でそのまま動作します。
+
+- **開発環境**では、開発サーバーの起動時に一時キーが自動的に生成されます。
+- **本番環境ビルド**では、ビルド中にランダムな32バイトのシークレットが生成され、ビルド成果物として保存されます。本番サーバーは起動時にこのキーを読み込みます。
+
+これはサーバ関数の暗号化が常に有効であることを意味します。独自の秘密鍵を提供したい場合や鍵のローテーションを有効にしたい場合にのみ設定が必要です。
+
+<Link name="custom-secret">
+## カスタムシークレット
+</Link>
+
+環境変数またはランタイム設定を使用して独自の暗号化シークレットを提供できます。これは、デプロイを跨いで決定論的なキーが必要な場合や、複数のサーバーインスタンスを実行する場合に有用です。
+
+シークレットは次の優先順位で解決されます。
+
+1. `REACT_SERVER_FUNCTIONS_SECRET` 環境変数
+2. `REACT_SERVER_FUNCTIONS_SECRET_FILE` 環境変数（キーファイルへのパス）
+3. ランタイム構成内の`serverFunctions.secret`
+4. ランタイム構成内の`serverFunctions.secretFile`（キーファイルへのパス）
+5. ビルド成果物 (本番ビルド時に自動生成)
+6. 一時的なランダムキー (開発時のフォールバック)
+
+<Link name="environment-variable">
+### 環境変数
+</Link>
+
+```sh
+REACT_SERVER_FUNCTIONS_SECRET=my-secret-key pnpm start
+```
+
+またはキーファイルを指定します。
+
+```sh
+REACT_SERVER_FUNCTIONS_SECRET_FILE=./keys/action-secret.pem pnpm start
+```
+
+<Link name="runtime-configuration">
+### ランタイム構成
+</Link>
+
+```mjs filename="react-server.config.mjs"
+export default {
+  serverFunctions: {
+    secret: "my-secret-key",
+  },
+};
+```
+
+またはキーファイルを指定します。
+
+```mjs filename="react-server.config.mjs"
+export default {
+  serverFunctions: {
+    secretFile: "./keys/action-secret.pem",
+  },
+};
+```
+
+> 環境変数と設定値は、常にビルド成果物よりも優先されます。これにより、アプリケーションを再構築せずにシークレットをローテーションできます。
+
+<Link name="key-rotation">
+## キーローテーション
+</Link>
+
+暗号化シークレットをローテーションすると、古いキーで暗号化されたトークンを含むページを開いたままのクライアントはエラーが発生します。これを回避するためにサーバーが復号時にフォールバックとして、サーバーが試行できる以前のシークレットを提供できます。
+
+```mjs filename="react-server.config.mjs"
+export default {
+  serverFunctions: {
+    secret: "new-secret-key",
+    previousSecrets: ["old-secret-key"],
+  },
+};
+```
+
+以前のシークレット用のキーファイルも使用できます。
+
+```mjs filename="react-server.config.mjs"
+export default {
+  serverFunctions: {
+    secret: "new-secret-key",
+    previousSecretFiles: ["./keys/old-secret.pem"],
+  },
+};
+```
+
+`previousSecrets`と`previousSecretFiles`の両方が配列を受け付けます。これらを組み合わせることで、複数の以前のキーを同時にサポートできます。
+
+ローテーションのワークフローは以下の通りです。
+
+1. 現在のシークレットを`previousSecrets`に追加する
+2. `secret`の新しい値を設定する
+3. デプロイ — 既存のトークンはすべてフォールバック経由で引き続き機能する
+4. すべてのクライアントが更新された後（例：デプロイメントウィンドウ終了後）、`previousSecrets`から古いシークレットを削除する
+
+<Link name="error-handling">
+## エラーハンドリング
+</Link>
+
+サーバ関数の呼び出しが復号に失敗した場合（例：トークンが改ざんされた、キーがローテーションされたが以前のキーが提供されなかった、トークンが無効であるなど）、サーバーは`ServerFunctionNotFoundError`をスローします。このエラーはRSCを通じてクライアントに伝播され、エラーバウンダリを使用してキャッチできます。
+
+これによりアプリケーション内に存在するサーバ関数に関する情報が漏れるのを防ぎます。
+
+<Link name="security-model">
+## セキュリティモデル
+</Link>
+
+暗号化は以下のセキュリティ特性を提供します。
+
+- **サーバ関数の隠蔽** — クライアントは暗号化されたトークンからサーバ関数のファイルパスや名前を特定できません。
+- **機能保護** — クライアントはサーバーがレンダリング時に明示的に公開した関数、またはクライアントコードにバンドルされた関数のみを呼び出せます。任意のサーバ関数に対するトークンを偽造することはできません。
+- **トークンの一意性** — 各サーバ関数参照には一意の暗号化トークン（ランダムな初期化ベクトル）が付与され、トークンの予測を不可能にします。
+- **キーローテーション** — `previousSecrets`設定を使用することで、ダウンタイムや再構築なしに実行時にシークレットをローテーションできます。
+
+> 暗号化はどのサーバ関数が呼び出し可能であるかを保護するものであり、それらの関数に渡される引数の内容まで妥当性を検証するわけではありません。サーバ関数の内部では、常に引数のバリデーションとサニタイズを行ってください。