{"id":15415,"plugin_id":"plugin_asdk_app_6a2c0bf33cb48191884d842b15ad3c20","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:11:22.606Z","digest":"09663ffd97e77ddef5f2db87564c4b4e9e29ee05f78fb857dcff52856bfdacb7","against":null,"payload":{"name":"mapbox-token-security","description":"Security best practices for Mapbox access tokens, including scope management, URL restrictions, rotation strategies, and protecting sensitive data. Use when creating, managing, or advising on Mapbox token security.","included_files":[{"relative_path":"AGENTS.md","size_in_bytes":5961},{"relative_path":"evals/evals.json","size_in_bytes":3484},{"relative_path":"references/incident-response.md","size_in_bytes":2342},{"relative_path":"references/rotation-monitoring.md","size_in_bytes":2039},{"relative_path":"references/token-management.md","size_in_bytes":1079}],"skill_md_contents":"---\nname: mapbox-token-security\ndescription: Security best practices for Mapbox access tokens, including scope management, URL restrictions, rotation strategies, and protecting sensitive data. Use when creating, managing, or advising on Mapbox token security.\n---\n\n# Mapbox Token Security Skill\n\nThis skill provides security expertise for managing Mapbox access tokens safely and effectively.\n\n## Token Types and When to Use Them\n\n### Public Tokens (pk.\\*)\n\n**Characteristics:**\n\n- Can be safely exposed in client-side code\n- Limited to specific public scopes only\n- Can have URL restrictions\n- Cannot access sensitive APIs\n\n**When to use:**\n\n- Client-side web applications\n- Mobile apps\n- Public-facing demos\n- Embedded maps on websites\n\n**Allowed scopes:**\n\n- `styles:tiles` - Display style tiles (raster)\n- `styles:read` - Read style specifications\n- `fonts:read` - Access Mapbox fonts\n- `datasets:read` - Read dataset data\n- `vision:read` - Vision API access\n\n### Secret Tokens (sk.\\*)\n\n**Characteristics:**\n\n- **NEVER expose in client-side code**\n- Full API access with any scopes\n- Server-side use only\n- Can create/manage other tokens\n\n**When to use:**\n\n- Server-side applications\n- Backend services\n- CI/CD pipelines\n- Administrative tasks\n- Token management\n\n**Common scopes:**\n\n- `styles:write` - Create/modify styles\n- `styles:list` - List all styles\n- `tokens:read` - View token information\n- `tokens:write` - Create/modify tokens\n- User feedback management scopes\n\n### Temporary Tokens (tk.\\*)\n\n**Characteristics:**\n\n- Short-lived (max 1 hour)\n- Created by secret tokens\n- Single-purpose use\n- Automatically expire\n\n**When to use:**\n\n- One-time operations\n- Temporary delegated access\n- Short-lived demos\n- Security-conscious workflows\n\n## Scope Management Best Practices\n\n### Principle of Least Privilege\n\n**Always grant the minimum scopes needed:**\n\n❌ **Bad:**\n\n```javascript\n// Overly permissive - don't do this\n{\n  scopes: ['styles:read', 'styles:write', 'styles:list', 'styles:delete', 'tokens:read', 'tokens:write'];\n}\n```\n\n✅ **Good:**\n\n```javascript\n// Only what's needed for displaying a map\n{\n  scopes: ['styles:read', 'fonts:read'];\n}\n// Add 'styles:tiles' if your map uses raster tile sources\n{\n  scopes: ['styles:read', 'fonts:read', 'styles:tiles'];\n}\n```\n\n### Scope Combinations by Use Case\n\n**Public Map Display (client-side):**\n\n```json\n{\n  \"scopes\": [\"styles:read\", \"fonts:read\", \"styles:tiles\"],\n  \"note\": \"Public token for map display\",\n  \"allowedUrls\": [\"https://myapp.com/*\"]\n}\n```\n\n**Style Management (server-side):**\n\n```json\n{\n  \"scopes\": [\"styles:read\", \"styles:write\", \"styles:list\"],\n  \"note\": \"Backend style management - SECRET TOKEN\"\n}\n```\n\n**Token Administration (server-side):**\n\n```json\n{\n  \"scopes\": [\"tokens:read\", \"tokens:write\"],\n  \"note\": \"Token management only - SECRET TOKEN\"\n}\n```\n\n**Read-Only Access:**\n\n```json\n{\n  \"scopes\": [\"styles:list\", \"styles:read\", \"tokens:read\"],\n  \"note\": \"Auditing/monitoring - SECRET TOKEN\"\n}\n```\n\n## URL Restrictions\n\n### Why URL Restrictions Matter\n\nURL restrictions limit where a public token can be used, preventing unauthorized usage if the token is exposed.\n\n### Effective URL Patterns\n\n✅ **Recommended patterns:**\n\n```\nhttps://myapp.com/*           # Production domain\nhttps://*.myapp.com/*         # All subdomains\nhttps://staging.myapp.com/*   # Staging environment\nhttp://localhost:*            # Local development\n```\n\n❌ **Avoid these:**\n\n```\n*                             # No restriction (insecure)\nhttp://*                      # Any HTTP site (insecure)\n*.com/*                       # Too broad\n```\n\n### Multiple Environment Strategy\n\nCreate separate tokens for each environment:\n\n```javascript\n// Production\n{\n  note: \"Production - myapp.com\",\n  scopes: [\"styles:read\", \"fonts:read\"],\n  allowedUrls: [\"https://myapp.com/*\", \"https://www.myapp.com/*\"]\n}\n\n// Staging\n{\n  note: \"Staging - staging.myapp.com\",\n  scopes: [\"styles:read\", \"fonts:read\"],\n  allowedUrls: [\"https://staging.myapp.com/*\"]\n}\n\n// Development\n{\n  note: \"Development - localhost\",\n  scopes: [\"styles:read\", \"fonts:read\"],\n  allowedUrls: [\"http://localhost:*\", \"http://127.0.0.1:*\"]\n}\n```\n\n## Token Storage and Handling\n\n### Server-Side (Secret Tokens)\n\n✅ **DO:**\n\n- Store in environment variables\n- Use secret management services (AWS Secrets Manager, HashiCorp Vault)\n- Encrypt at rest\n- Limit access via IAM policies\n- Log token usage\n\n❌ **DON'T:**\n\n- Hardcode in source code\n- Commit to version control\n- Store in plaintext configuration files\n- Share via email or Slack\n- Reuse across multiple services\n\n**Example: Secure Environment Variable:**\n\n```bash\n# .env (NEVER commit this file)\nMAPBOX_SECRET_TOKEN=sk.ey...\n\n# .gitignore (ALWAYS include .env)\n.env\n.env.local\n.env.*.local\n```\n\n### Client-Side (Public Tokens)\n\n✅ **DO:**\n\n- Use public tokens only\n- Apply URL restrictions\n- Use different tokens per app\n- Rotate periodically\n- Monitor usage\n\n❌ **DON'T:**\n\n- Expose secret tokens\n- Use tokens without URL restrictions\n- Share tokens between unrelated apps\n- Use tokens with excessive scopes\n\n**Example: Safe Client Usage (Vite):**\n\n> **Note:** This example uses **Vite**. For Next.js, CRA, Angular, or a plain `window.MAPBOX_ACCESS_TOKEN` / CDN setup, see [Token Management](references/token-management.md). Do not chain `import.meta.env` and `process.env` in one expression — the unused path throws `ReferenceError` in the browser.\n\n```javascript\n// Public token with URL restrictions - SAFE (Vite)\nconst mapboxToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;\n\n// Guard BEFORE constructing the map — missing tokens otherwise yield a silent blank map\nif (!mapboxToken || mapboxToken === 'YOUR_MAPBOX_ACCESS_TOKEN') {\n  throw new Error('Missing VITE_MAPBOX_ACCESS_TOKEN — set it in env before creating the map');\n}\n\nmapboxgl.accessToken = mapboxToken;\n```\n\n### Agent anti-pattern: skip the token guard\n\nAgents often assign `mapboxgl.accessToken` and call `new mapboxgl.Map(...)` with no check. That fails closed as a blank canvas with no UI error.\n\n**Always:**\n\n1. Resolve the token from the env pattern for your bundler (never hardcode a real `pk.` in source)\n2. Validate it is present and not a placeholder\n3. Only then set `accessToken` and construct the map\n\n## Security Checklist\n\n**Token Creation:**\n\n- [ ] Use public tokens for client-side, secret for server-side\n- [ ] Apply principle of least privilege for scopes\n- [ ] Add URL restrictions to public tokens\n- [ ] Use descriptive names/notes for token identification\n- [ ] Document intended use and environment\n\n**Token Management:**\n\n- [ ] Store secret tokens in environment variables or secret managers\n- [ ] Never commit tokens to version control\n- [ ] Rotate tokens every 90 days (or per policy)\n- [ ] Remove unused tokens promptly\n- [ ] Separate tokens by environment (dev/staging/prod)\n- [ ] Guard missing tokens in client code before `new mapboxgl.Map`\n\n**Monitoring:**\n\n- [ ] Track token usage patterns\n- [ ] Set up alerts for unusual activity\n- [ ] Regular security audits (monthly)\n- [ ] Review team access quarterly\n- [ ] Scan repositories for exposed tokens\n\n**Incident Response:**\n\n- [ ] Documented revocation procedure\n- [ ] Emergency contact list\n- [ ] Rotation process documented\n- [ ] Post-incident review template\n- [ ] Team training on security procedures\n\n## Reference Files\n\nFor detailed guidance on specific topics, load these references as needed:\n\n- **`references/token-management.md`** — Bundler-specific env var names and access patterns (Vite / Next / CRA / Angular / CDN). Load when: wiring tokens in a different framework than the Vite example above.\n- **`references/rotation-monitoring.md`** — Token rotation strategies (zero-downtime + emergency), monitoring metrics, alerting rules, and monthly/quarterly audit checklists. Load when: implementing rotation, setting up monitoring, or conducting audits.\n- **`references/incident-response.md`** — Step-by-step incident response plan and common security mistakes with code examples. Load when: responding to a token compromise, reviewing code for security issues, or training on anti-patterns.\n\n## When to Use This Skill\n\nInvoke this skill when:\n\n- Creating new tokens\n- Deciding between public vs secret tokens\n- Setting up token restrictions\n- Implementing token rotation\n- Investigating security incidents\n- Conducting security audits\n- Training team on token security\n- Reviewing code for token exposure\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}