mapbox-token-security

Mapbox 令牌安全技能

此技能提供 Mapbox 访问令牌管理方面的安全专业知识，帮助你安全、有效地管理令牌。

令牌类型及适用场景

公共令牌（pk.*）

特点：

• 可以安全地公开在客户端代码中
• 仅限特定的公共权限范围
• 可以设置 URL 限制
• 无法访问敏感 API

适用场景：

• 客户端 Web 应用
• 移动应用
• 面向公众的演示
• 网站中嵌入的地图

允许的权限范围：

• styles:tiles - 显示样式图块（栅格）
• styles:read - 读取样式规范
• fonts:read - 访问 Mapbox 字体
• datasets:read - 读取数据集数据
• vision:read - 访问视觉 API

密钥令牌（sk.*）

特点：

• 绝不可公开在客户端代码中
• 可通过任意权限范围访问完整 API
• 仅限服务端使用
• 可以创建和管理其他令牌

适用场景：

• 服务端应用
• 后端服务
• CI/CD 流水线
• 管理任务
• 令牌管理

常见权限范围：

• styles:write - 创建或修改样式
• styles:list - 列出所有样式
• tokens:read - 查看令牌信息
• tokens:write - 创建或修改令牌
• 用户反馈管理权限范围

临时令牌（tk.*）

特点：

• 有效期短（最长 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 配置，请参阅令牌管理。不要在同一个表达式中串联 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;

Agent 反面模式：跳过令牌检查

Agent 经常直接赋值 mapboxgl.accessToken 并调用 new mapboxgl.Map(...)，却不做任何检查。这样失败时只会显示空白画布，不会出现 UI 错误提示。

务必：

1. 根据打包工具使用相应的环境变量模式获取令牌（切勿在源代码中硬编码真实的 pk. 令牌）
2. 验证令牌存在且不是占位符
3. 仅在此之后设置 accessToken 并创建地图

安全检查清单

创建令牌：

• 客户端使用公开令牌，服务端使用机密令牌
• 按照最小权限原则设置作用域
• 为公开令牌添加 URL 限制
• 使用描述性名称/备注以便识别令牌
• 记录预期用途和环境

令牌管理：

• 将机密令牌存储在环境变量或密钥管理器中
• 切勿将令牌提交到版本控制系统
• 每 90 天（或按政策要求）轮换令牌
• 及时删除未使用的令牌
• 按环境区分令牌（开发/预发布/生产）
• 在执行 new mapboxgl.Map 前，于客户端代码中检查令牌是否缺失

监控：

• 跟踪令牌使用模式
• 为异常活动设置警报
• 定期进行安全审计（每月）
• 每季度审查团队访问权限
• 扫描代码仓库，查找泄露的令牌

事件响应：

• 编写撤销流程文档
• 紧急联系人名单
• 记录轮换流程
• 事后审查模板
• 为团队提供安全流程培训

参考文件

如需了解特定主题的详细指导，请按需加载以下参考资料：

• references/token-management.md — 特定打包工具的环境变量名称和访问模式（Vite / Next / CRA / Angular / CDN）。适用于：在不同于上文 Vite 示例的框架中接入令牌。
• references/rotation-monitoring.md — 令牌轮换策略（零停机 + 紧急轮换）、监控指标、警报规则以及月度/季度审计清单。适用于：实施轮换、设置监控或开展审计。
• references/incident-response.md — 逐步事件响应计划，以及附有代码示例的常见安全错误。适用于：应对令牌泄露、审查代码中的安全问题，或开展反模式培训。

何时使用此技能

在以下情况下调用此技能：

• 创建新令牌
• 决定使用公开令牌还是机密令牌
• 设置令牌限制
• 实施令牌轮换
• 调查安全事件
• 开展安全审计
• 为团队提供令牌安全培训
• 审查代码中的令牌泄露情况