シークレット:サイトのコードに必要なキー

#シークレットとは

シークレットとは、名前の付いた値のことです。値の多くはAPIキーで、あるプログラムが別のプログラムと通信するためのパスワードのようなものです。たとえばメール配信サービスから渡されるキーです。名前は、サイトのコードがその値を呼び出すためのもので、たとえば MAILING_LIST_KEY です。

シークレットを読み取るサイトの部分は、サーバー上でルートの背後で動きます。ルートとは、ページを表示せずコードを実行する、/api/ 以下のアドレスです。値はサーバーの中にとどまります。サイトのページにも、訪問者のブラウザにも、ダウンロードできるコードにも含まれません。

一度保存した値は、誰にも、あなたにも、二度と表示されません。スタジオに残るのは名前と、保存した人、保存した日時だけです。パスワードマネージャーなど、安全な場所にご自身で控えを保管してください。

シークレットが必要になるのは、サイト自体のコードがキーを必要とする外部サービスと連携するときだけです。お問い合わせフォームのあるパンフレット的なサイトなら、必要ありません。

#始める前に

• まずサイトを一度公開してください。 シークレットは公開済みのサイトにのみ保管され、スタジオには保管されません。初回の公開までは、ページに Publish the site first と表示され、何も追加できません。
• ロールを確認してください。 Editor、Admin、Ownerはシークレットの追加、変更、削除ができます。Viewerは名前と保存日時を見ることができます。
• 名前を付けます。 英字、数字、アンダースコアが使え、先頭は英字で、128文字までです。大文字とアンダースコアの組み合わせが一般的です。BRIKS_で始まる名前はスタジオ用に予約されています。
• 上限にご注意ください。 値は最大5 KBで、どんなキーや証明書にも十分な大きさです。1つのプロジェクトに保存できるシークレットは、スタジオ自身のものを含めて最大100個です。

#シークレットを追加

#.env ファイルから複数まとめてインポート

.env ファイルは、シークレットごとに NAME=value の行を並べたテキストファイルです。開発者がよく使います。お持ちの場合は、すべての行を一度に取り込めます。

#シークレットを変更または削除する

変更は公開中のサイトにすぐ反映されます。追加や更新では The live site has it now、削除では The live site no longer has it と表示されます。シークレットが多い場合は、Search secrets ボックスで名前から探せます。表には各シークレットの Name と Last saved が表示され、保存した人も分かります。

一部の行には Managed タグが付いています。これはサイトのメールなど、スタジオ自身のサービスのために設定されたもので、ここでは変更も削除もできません。

#ビルドがシークレットを使う仕組み

サイトのコードは、実行のたびにシークレットを名前で読み取るため、構築時に値は必要ありません。メーリングリストやAIモデルなど、ほかのサービスとサイトをつなぐようスタジオに頼むと、そのサービスのキーを MAILING_LIST_KEY のようなわかりやすい名前でコードが読み取ります。値は、その名前でここに追加します。

#構築の前にキーを求められたとき

• 公開済みサイトへの変更。 リクエストが別のサービスにつながる場合、ステータスにはしばらく Checking which keys this needs と表示されます。サイトにまだ値がないキーがあれば、スタジオはビルドの前に確認します。会話内のカードには、キーごとの入力欄があり、1回の変更で最大3つまで表示されます。値を貼り付けて Save and build を押すと、値は会話ではなくサイトのSecretsに直接保存され、変更が始まります。Add it later を押すと、値なしでビルドします。
• 待っている間に送ったメッセージ は、その変更に加わります。すでに保存したキーや、後で追加すると選んだキーが再び求められることはありません。新しいメッセージで別のサービスをつなぐ場合は、最初のカードが完了した後に、そのキーだけが求められます。
• 新しいサイト。 Secrets を使うには公開済みのサイトが必要なため、最初の構築ではまだキーを受け付けられません。構築前の質問の中で、今すぐ連携を作ってサイト公開後にキーを追加するか、その部分を今回は含めないかを尋ねることがあります。
• Telegramでは、カードに各キー用のボタンがあり、スタジオのSecretsが開きます。続けるには Build を押します。キーがチャットで送られることはありません。

#サイトで必要

公開のたびに、Briksはサイト自身のコードが要求するシークレット名を読み取ります。まだ値がないものは、このページの先頭に Needed by the site のタグ付きで表示されます。その1つで Add value を押すと、名前が入力済みのフォームが開きます。名前に値が入るまで、それを使うサイトの部分は動きません。

ビルドや変更への返信にも、その名前が書かれます。例：サイトは MAILING_LIST_KEY を読み込みますが、まだ値がありません。Project Settings → Secrets で追加してください。名前ごとに Add MAILING_LIST_KEY のようなボタンがあり、押すと名前が入力済みのこのページが開きます。同じ文は通知にも入り、ビルド完了をお知らせするTelegramにも入ります。

#メッセージに貼り付けたキー

Briksは、サービスキーやトークンのよくある形式を見分けます。スタジオのチャット、新しいプロジェクトの説明、プロジェクトのブリーフ、エージェントへのメッセージや指示、ビジュアルエディターのAIに質問、ボットとのチャットに貼り付けられたキーは、メッセージが保存または読み取られる前に取り除かれ、[key removed: add it in Settings → Secrets] に置き換えられます。スタジオはすぐに「A key was removed from your message so it isn't stored. Add it in Project Settings → Secrets.」と知らせます。返信には、このページへの Open Secrets ボタンがあります。すべてのプロジェクトで働くエージェントのスレッドでは、Open Secrets にプロジェクトの一覧が表示されるので、キーの対象のプロジェクトを選べます。エージェントに覚えさせたい内容にキーが含まれている場合は、受け付けられません。

サイトを公開する前に、Briksは自身のコードを読み、ファイルに書き込まれたキーを探します。形からキーと思われる値や、キー、トークン、パスワードのような名前の項目に渡された値が対象です。見つかった場合は、ビルドが差し戻され、値を取り除いて、代わりに名前でシークレットを読み込むようにします。

#Briksが適用するセキュリティルール

• 入力した値は暗号化され、公開サイトのサーバー側へ直接送られます。スタジオは値を保存せず、再表示もせず、ログにも書き込みません。
• 値がサイトのページ、訪問者のブラウザ、ダウンロードしたコードに表示されることはありません。
• シークレットを追加、変更、削除できるのは、Editor、Admin、Ownerだけです。
• BRIKS_で始まる名前はスタジオ用で、管理されているシークレットは変更できません。
• プロジェクトでは、シークレットの変更を1分間に最大60回まで行えます。それを超えると次のように表示されます: That is a lot of changes at once. Wait a minute and try again.

#シークレットが見つからないとき

シークレットはサイトのアドレスに紐づきます。アドレスを変更すると（サイトのアドレスをご覧ください）、シークレットは古いアドレスに残ります。スタジオのメッセージにそれらが一覧され、Settings, Secrets で入力し直すよう案内され、各行に Not on the site · enter again と表示されます。それぞれで Edit value を選び、値を貼り付けます。

サイトのコードが、存在しないシークレットを要求すると、サイトのその部分は「Part of this site is not set up yet」と応答します。名前が大文字も含めて完全に一致しているか、また、その行に Not on the site と表示されていないかを確認してください。

#実例:漏えいしたキーを差し替える

その後で初めて、メール配信サービス上の古いキーを削除しました。そのためサイトは、有効なキーがない瞬間が一度もありませんでした。コードはキーを名前で呼び出すので、何も作り直す必要はありませんでした。