API キーとセキュリティ

API キーの仕組み

Settings → MCP / API で API キーを作成すると、Clarity は以下を実行します：

1. 1Node.js の crypto.randomBytes を使用して 32 バイトの暗号学的に安全なランダムバイト を生成
2. 2base64url 文字列としてエンコードし、sk_clarity_ プレフィックスを付加
3. 3完全なキーの SHA-256 ハッシュ を計算
4. 4データベースには ハッシュのみを保存
5. 5平文キーを 1 回だけ 返却

認証フロー

すべての MCP API リクエストは以下のパスをたどります：

1. 1AI クライアントが Authorization: Bearer ヘッダーで平文キーを送信
2. 2Clarity API が受信キーを SHA-256 でハッシュ化
3. 3タイミングセーフ比較（crypto.timingSafeEqual）を使用して、すべての有効なキーハッシュと比較
4. 4一致した場合、関連付けられた user_id を取得して処理を続行

所有権の検証

キー管理のベストプラクティス

• わかりやすいラベルを使用 — クライアント名でキーに名前を付けてください
• クライアントごとに 1 つのキー — 複数のマシンで同じキーを再利用しないでください
• 定期的にローテーション — 数か月ごとに新しいキーを生成してください
• キーをコミットしない — MCP 設定を .gitignore に追加してください

キーの制限

MCP でできること・できないこと

MCP でできること：

• すべてのプロジェクトを一覧表示し、ファイルツリーを閲覧
• プロジェクト内のファイルの読み取り、書き込み、作成、削除
• LaTeX および Typst ドキュメントのコンパイル
• コンパイルエラーのデバッグ
• Typst ドキュメントの検索
• TikZ イラストの生成

MCP でできないこと：

• プロジェクト全体の作成や削除
• メインエントリファイルの削除
• 空でないフォルダの削除
• バイナリファイルのアップロード
• 他のユーザーのデータへのアクセス
• アカウント設定の変更
• 課金情報へのアクセス
• 所有権検証のバイパス

監査証跡

API キーが使用されるたびに、Clarity は Settings → MCP / API に表示される 最終使用日時 のタイムスタンプを更新します。