Mapbox Token Security Skill

このスキルは、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時間）
• シークレットトークンから作成
• 単一目的の使用
• 自動的に有効期限切れ

使用場面:

• ワンタイム操作
• 一時的な委譲アクセス
• 短命デモ
• セキュリティを意識したワークフロー

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

最小権限の原則

必要最小限のスコープのみを付与する:

❌ 悪い例:

// 過度に寛容 - これはしないこと
{
  scopes: ['styles:read', 'styles:write', 'styles:list', 'styles:delete', 'tokens:read', 'tokens:write'];
}

✅ 良い例:

// マップ表示に必要なもののみ
{
  scopes: ['styles:read', 'fonts:read'];
}
// マップがラスタタイルソースを使用する場合は 'styles:tiles' を追加
{
  scopes: ['styles:read', 'fonts:read', 'styles:tiles'];
}

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

パブリックマップ表示 (クライアント側):

{
  "scopes": ["styles:read", "fonts:read", "styles:tiles"],
  "note": "マップ表示用のパブリックトークン",
  "allowedUrls": ["https://myapp.com/*"]
}

スタイル管理 (サーバー側):

{
  "scopes": ["styles:read", "styles:write", "styles:list"],
  "note": "バックエンドスタイル管理 - シークレットトークン"
}

トークン管理 (サーバー側):

{
  "scopes": ["tokens:read", "tokens:write"],
  "note": "トークン管理のみ - シークレットトークン"
}

読み取り専用アクセス:

{
  "scopes": ["styles:list", "styles:read", "tokens:read"],
  "note": "監査・監視 - シークレットトークン"
}

URL制限

URL制限が重要な理由

URL制限はパブリックトークンの使用場所を限定し、トークンが漏洩した場合の不正使用を防止します。

効果的な URL パターン

✅ 推奨パターン:

https://myapp.com/*           # 本番ドメイン
https://*.myapp.com/*         # すべてのサブドメイン
https://staging.myapp.com/*   # ステージング環境
http://localhost:*            # ローカル開発

❌ 避けるべきもの:

*                             # 制限なし（安全でない）
http://*                      # あらゆる HTTP サイト（安全でない）
*.com/*                       # 範囲が広すぎる

複数環境戦略

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

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

// ステージング
{
  note: "ステージング - staging.myapp.com",
  scopes: ["styles:read", "fonts:read"],
  allowedUrls: ["https://staging.myapp.com/*"]
}

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

トークンの保存と処理

サーバー側 (シークレットトークン)

✅ 実施すること:

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

❌ 実施しないこと:

• ソースコードにハードコード
• バージョン管理にコミット
• プレーンテキスト設定ファイルに保存
• メールやSlackで共有
• 複数のサービスで再利用

例: セキュアな環境変数:

# .env (このファイルを絶対にコミットしないこと)
MAPBOX_SECRET_TOKEN=sk.ey...

# .gitignore (常に .env を含める)
.env
.env.local
.env.*.local

クライアント側 (パブリックトークン)

✅ 実施すること:

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

❌ 実施しないこと:

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

例: 安全なクライアント使用:

// URL制限付きのパブリックトークン - 安全
const mapboxToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';

// このトークンはあなたのドメインに制限されており、
// styles:read スコープのみを持っています
mapboxgl.accessToken = mapboxToken;

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

トークン作成:

• クライアント側はパブリックトークン、サーバー側はシークレットトークンを使用
• スコープに最小権限の原則を適用
• パブリックトークンに URL 制限を追加
• トークン識別用に説明的な名前・メモを付与
• 意図された用途と環境を文書化

トークン管理:

• シークレットトークンを環境変数またはシークレット管理ツールに保存
• トークンをバージョン管理にコミットしない
• 90日ごと（またはポリシーに従い）トークンをローテーション
• 未使用のトークンをすぐに削除
• 環境（開発・ステージング・本番）ごとにトークンを分離

監視:

• トークン使用パターンを追跡
• 異常なアクティビティに対するアラートを設定
• 定期的なセキュリティ監査（月次）
• チームアクセスを四半期ごとにレビュー
• 公開されたトークンについてリポジトリをスキャン

インシデント対応:

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

参考ファイル

特定のトピックに関する詳細なガイダンスについては、必要に応じてこれらの参考資料をロードしてください:

• references/rotation-monitoring.md — トークンローテーション戦略（ゼロダウンタイム + 緊急対応）、監視メトリクス、アラートルール、月次・四半期監査チェックリスト。ロード対象: ローテーション実装時、監視設定時、または監査実施時。
• references/incident-response.md — ステップバイステップのインシデント対応計画と一般的なセキュリティミスのコード例。ロード対象: トークン侵害対応時、コードのセキュリティレビュー時、またはアンチパターン研修時。

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

以下の場合にこのスキルを適用してください:

• 新しいトークンを作成
• パブリックトークンとシークレットトークンのどちらかを決定
• トークン制限を設定
• トークンローテーションを実装
• セキュリティインシデントを調査
• セキュリティ監査を実施
• チームにトークンセキュリティに関する研修を提供
• トークン公開についてコードをレビュー