mapbox-token-security

Mapbox トークンのセキュリティスキル

このスキルでは、Mapbox アクセストークンを安全かつ効果的に管理するためのセキュリティに関する知識を提供します。

トークンの種類と使用する場面

パブリックトークン（pk.*）

特徴：

• クライアントサイドのコードで安全に公開できます
• 特定のパブリックスコープのみに制限されます
• URL 制限を設定できます
• 機密性の高い API にはアクセスできません

使用する場面：

• クライアントサイドのウェブアプリケーション
• モバイルアプリ
• 一般公開のデモ
• ウェブサイトに埋め込むマップ

許可されるスコープ：

• styles:tiles - スタイルタイル（ラスター）を表示します
• styles:read - スタイルの仕様を読み取ります
• fonts:read - Mapbox フォントにアクセスします
• datasets:read - データセットのデータを読み取ります
• vision:read - Vision API にアクセスします

シークレットトークン（sk.*）

特徴：

• クライアントサイドのコードでは絶対に公開しないでください
• あらゆるスコープで API にフルアクセスできます
• サーバーサイドでのみ使用します
• 他のトークンを作成・管理できます

使用する場面：

• サーバーサイドアプリケーション
• バックエンドサービス
• CI/CD パイプライン
• 管理タスク
• トークン管理

一般的なスコープ：

• styles:write - スタイルを作成・変更します
• styles:list - すべてのスタイルを一覧表示します
• tokens:read - トークン情報を表示します
• tokens:write - トークンを作成・変更します
• ユーザーフィードバック管理のスコープ

一時トークン（tk.*）

特徴：

• 有効期間が短い（最大 1 時間）
• シークレットトークンによって作成されます
• 単一目的で使用します
• 自動的に有効期限が切れます

使用する場面：

• 1 回限りの操作
• 一時的に委任するアクセス
• 短期間のデモ
• セキュリティを重視するワークフロー

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

最小権限の原則

必要最小限のスコープのみを常に付与してください：

❌ 悪い例：

// Overly permissive - don't do this
{
  scopes: ['styles:read', 'styles:write', 'styles:list', 'styles:delete', 'tokens:read', 'tokens:write'];
}

✅ 良い例：

// Only what's needed for displaying a map
{
  scopes: ['styles:read', 'fonts:read'];
}
// Add 'styles:tiles' if your map uses raster tile sources
{
  scopes: ['styles:read', 'fonts:read', 'styles:tiles'];
}

ユースケース別のスコープの組み合わせ

パブリックマップの表示（クライアントサイド）：

{
  "scopes": ["styles:read", "fonts:read", "styles:tiles"],
  "note": "Public token for map display",
  "allowedUrls": ["https://myapp.com/*"]
}

スタイル管理（サーバーサイド）：

{
  "scopes": ["styles:read", "styles:write", "styles:list"],
  "note": "Backend style management - SECRET TOKEN"
}

トークン管理（サーバーサイド）：

{
  "scopes": ["tokens:read", "tokens:write"],
  "note": "Token management only - SECRET TOKEN"
}

読み取り専用アクセス：

{
  "scopes": ["styles:list", "styles:read", "tokens:read"],
  "note": "Auditing/monitoring - SECRET TOKEN"
}

URL 制限

URL 制限が重要な理由

URL 制限を設定すると、パブリックトークンを使用できる場所を限定できるため、トークンが公開された場合の不正使用を防止できます。

効果的な URL パターン

✅ 推奨パターン：

https://myapp.com/*           # Production domain
https://*.myapp.com/*         # All subdomains
https://staging.myapp.com/*   # Staging environment
http://localhost:*            # Local development

❌ 次のパターンは避けてください：

*                             # No restriction (insecure)
http://*                      # Any HTTP site (insecure)
*.com/*                       # Too broad

複数環境での運用方法

環境ごとに個別のトークンを作成します：

// Production
{
  note: "Production - myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://myapp.com/*", "https://www.myapp.com/*"]
}

// Staging
{
  note: "Staging - staging.myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://staging.myapp.com/*"]
}

// Development
{
  note: "Development - localhost",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["http://localhost:*", "http://127.0.0.1:*"]
}

トークンの保管と取り扱い

サーバーサイド（シークレットトークン）

✅ 推奨事項：

• 環境変数に保存します
• シークレット管理サービス（AWS Secrets Manager、HashiCorp Vault）を使用します
• 保存時に暗号化します
• IAM ポリシーを使用してアクセスを制限します
• トークンの使用状況をログに記録します

❌ 禁止事項：

• ソースコードにハードコードしないでください
• バージョン管理にコミットしないでください
• 平文の設定ファイルに保存しないでください
• メールや Slack で共有しないでください
• 複数のサービスで使い回さないでください

例：安全な環境変数：

# .env (NEVER commit this file)
MAPBOX_SECRET_TOKEN=sk.ey...

# .gitignore (ALWAYS include .env)
.env
.env.local
.env.*.local

クライアントサイド（パブリックトークン）

✅ 推奨事項：

• パブリックトークンのみを使用します
• URL 制限を適用します
• アプリごとに異なるトークンを使用します
• 定期的にローテーションします
• 使用状況を監視します

❌ 禁止事項：

• シークレットトークンを公開しないでください
• URL 制限のないトークンを使用しないでください
• 関連のないアプリ間でトークンを共有しないでください
• 過剰なスコープを持つトークンを使用しないでください

例：安全なクライアントでの使用（Vite）：

注： この例では Vite を使用しています。Next.js、CRA、Angular、またはプレーンな window.MAPBOX_ACCESS_TOKEN / CDN の構成については、トークン管理を参照してください。1 つの式で import.meta.env と process.env を連結しないでください。未使用のパスはブラウザーで ReferenceError を発生させます。

// Public token with URL restrictions - SAFE (Vite)
const mapboxToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

// Guard BEFORE constructing the map — missing tokens otherwise yield a silent blank map
if (!mapboxToken || mapboxToken === 'YOUR_MAPBOX_ACCESS_TOKEN') {
  throw new Error('Missing VITE_MAPBOX_ACCESS_TOKEN — set it in env before creating the map');
}

mapboxgl.accessToken = mapboxToken;

エージェントのアンチパターン：トークンチェックを省略する

エージェントは mapboxgl.accessToken を設定し、チェックを行わずに new mapboxgl.Map(...) を呼び出すことがよくあります。その場合、UI エラーが表示されないまま、空白のキャンバスでフェイルクローズします。

必ず次の手順を実行してください：

1. 使用するバンドラーの環境変数パターンからトークンを取得します（実際の pk. をソースコードにハードコードしないでください）
2. トークンが存在し、プレースホルダーではないことを検証します
3. その後でのみ accessToken を設定し、マップを生成します

セキュリティチェックリスト

トークンの作成：

• クライアント側ではパブリックトークンを、サーバー側ではシークレットトークンを使用する
• スコープには最小権限の原則を適用する
• パブリックトークンに URL 制限を追加する
• トークンを識別できるよう、内容がわかる名前やメモを付ける
• 想定される用途と環境を記録する

トークンの管理：

• シークレットトークンは環境変数またはシークレットマネージャーに保存する
• トークンをバージョン管理にコミットしない
• 90 日ごと（またはポリシーに従って）トークンをローテーションする
• 使用していないトークンは速やかに削除する
• 環境（dev/staging/prod）ごとにトークンを分ける
• new mapboxgl.Map の前に、クライアントコードでトークンがない場合の処理を行う

モニタリング：

• トークンの使用パターンを追跡する
• 不審なアクティビティに対するアラートを設定する
• 定期的にセキュリティ監査を実施する（月次）
• チームのアクセス権を四半期ごとに確認する
• リポジトリをスキャンして、漏えいしたトークンがないか確認する

インシデント対応：

• 文書化された失効手順
• 緊急連絡先リスト
• ローテーション手順の文書化
• インシデント後レビューのテンプレート
• セキュリティ手順に関するチーム研修

参考ファイル

特定のトピックに関する詳しいガイダンスが必要な場合は、必要に応じて次の参考資料を読み込んでください。

• references/token-management.md — バンドラーごとの環境変数名とアクセスパターン（Vite / Next / CRA / Angular / CDN）。読み込む場面：上記の Vite の例とは異なるフレームワークでトークンを設定する場合。
• references/rotation-monitoring.md — トークンのローテーション戦略（ダウンタイムなしのローテーションと緊急ローテーション）、モニタリング指標、アラートルール、月次・四半期ごとの監査チェックリスト。読み込む場面：ローテーションの実装、モニタリングの設定、監査の実施を行う場合。
• references/incident-response.md — インシデント対応の手順と、コード例を交えたよくあるセキュリティ上のミス。読み込む場面：トークン漏えいへの対応、セキュリティ上の問題がないかコードをレビューする場合、アンチパターンに関する研修を行う場合。

このスキルを使用する場面

次の場合にこのスキルを呼び出してください。

• 新しいトークンを作成する
• パブリックトークンとシークレットトークンのどちらを使用するか判断する
• トークンの制限を設定する
• トークンのローテーションを実装する
• セキュリティインシデントを調査する
• セキュリティ監査を実施する
• トークンのセキュリティについてチームをトレーニングする
• トークンの漏えいがないかコードをレビューする