Box コネクター

English: Box connector

項目	内容
プラグイン ID	box（同梱、既定は無効）
既定のアクセス	読み取り専用：root_readonly
追加で有効にできるもの	指定した 1 つのフォルダーへのプロジェクトファイルのアップロード（root_readwrite）。毎回、人が承認
サインイン	ループバック リダイレクトによる OAuth 2.0 認可コード。クライアントシークレットはシークレット ストア
トークンの保存先	Kurahi のシークレット ストア（connector.box.token）
状態	提供中

ツール

ツール	必要な権限	内容
box_search	root_readonly	ファイル検索（名前と本文）。ID、名前、パス、サイズ、更新日時。最大 50 件。searchFolderIds があればその中だけ
box_file_metadata	root_readonly	名前、パス、サイズ、種類、日時、バージョン、SHA-1
box_file_fetch	root_readonly、プロジェクトのチャット	ファイルを 1 つプロジェクトに取り込む（下記）
box_file_upload（write.upload）	root_readwrite と承認	プロジェクトのファイルを write.uploadFolderId にアップロード

ファイルの取り込み：バイトはモデルに渡しません

box_file_fetch はプロジェクトのチャットでだけ使えます。まずファイルサイズを確認し、20 MB を 超えるものはダウンロードせずに拒否します。それ以外はファイルをダウンロード（GET /files/{id}/content。 有効期間の短いダウンロード URL へリダイレクトされます）し、コアの 添付ファイル取り込み に渡します。プロジェクトのデータ領域での隔離、 静的ポリシー（実行ファイル、スクリプト、マクロ、暗号化ファイル、多重アーカイブ、不明な形式は拒否）、 マルウェアスキャン（失敗時は拒否）を経て、問題がない場合だけプロジェクトの inbox-attachments/ に コピーします。モデルが受け取るのは保存先のパスと、信頼できないコンテンツの境界内の抽出テキストだけで、 バイトは渡しません。拒否はコード付きの通常の結果として返し、監査と証跡の封印を行います。 box_file_fetch は m365_mail_attachment_fetch と同じく、オートパイロットの収集ツールとして宣言されて います。

アップロードは必ず人が承認

box_file_upload は write.upload と write.uploadFolderId（ルートフォルダー 0 は不可）がある場合だけ 登録されます。受け付けるのはプロジェクト内の文書ファイル（PDF、DOCX、XLSX、PPTX、CSV、TXT、MD、画像）で 最大 20 MB。承認依頼（フォルダー、ファイル名、サイズ、種類）を送り、人が承認した後にだけアップロード します。同名ファイルがあると失敗し（Box は 409 を返します）、上書きはせず、共有リンクも作りません。 Box でコンテンツを書き込めるスコープは root_readwrite だけで、Box 上はほかの変更も可能になりますが、 コネクターにはこのアップロード以外に使うツールがありません。

設定

1. Box 開発者コンソールで カスタムアプリ（ユーザー認証（OAuth 2.0））を作成します。 リダイレクト URI に http://localhost/callback を追加します（localhost は任意のポートで可）。 アプリケーションスコープ で すべてのファイルとフォルダーの読み取り を、アップロードする場合 だけ すべてのファイルとフォルダーへの書き込み も選びます。Box 管理者によるアプリの承認が必要な 場合があります。
2. 設定します。

kurahi plugins enable box
kurahi secrets set connector.box.clientSecret
kurahi config set plugins.entries.box.config '{ "clientId": "<32 文字の client id>" }' --json
kurahi box status
kurahi box login
kurahi box probe

キー	既定値	意味
clientId	なし	Box アプリの Client ID
searchFolderIds	なし	検索をこれらのフォルダー内に限定
write.upload	false	box_file_upload
write.uploadFolderId	なし	アップロード先のフォルダー（1 つ）
redirectPort	ランダム	ループバックのポートを固定
ratePerSecond	4	クライアント側の上限（検索は毎分 50 回）
approvalTimeoutSeconds	120	アップロードが人の承認を待つ時間

データの扱い

• 信頼できないコンテンツ：ファイル名、パス、抽出テキストは、信頼できないコンテンツの境界の内側で だけモデルに渡します。
• 監査：呼び出しごとに 1 行（connector.box.<operation>）。ファイル ID、件数、バイト数、文書の種類、 所要時間、エラーコードのみ。ファイル名、パス、検索語、内容は記録しません。
• トークン：アクセストークンは 60 分、リフレッシュトークンは 60 日で 1 回限り（更新のたびに入れ替え）。
• 上限：Box はユーザーあたり毎分 1,000 リクエスト、検索は毎秒 6 回・毎分 60 回、アップロードは 毎分 240 回です。コネクターは自らレート制限し、検索は毎分 50 回に抑えます。
• 接続先：account.box.com、api.box.com、upload.box.com と、Box がリダイレクトするダウンロード URL。

状態と取り消し

ゲートウェイは GET /users/me?fields=id でプローブします。kurahi box logout は /oauth2/revoke で （クライアント資格情報付きで）トークンを取り消し、ローカルからも削除します。

参考資料

Box 公式ドキュメント：OAuth のエンドポイントとエラー、取り消し、トークンの有効期間、localhost の リダイレクト規則、スコープ、検索・ファイル・ダウンロード・アップロードの API、レート制限。出典 URL は 英語版 にあります。

設定のメモ：サインインは PKCE を送信します（未対応の環境では無視されます）。プローブは GET /users/me を使います。サインインは OAuth 2.0 で、JWT（サーバー）認証はこのリリースでは対象外です。