syncfusion-blazor-maps

What this skill does

# Implementing Syncfusion Maps for Blazor

**NuGet:** `Syncfusion.Blazor.Maps` + `Syncfusion.Blazor.Themes`
**Namespace:** `Syncfusion.Blazor.Maps`

A comprehensive guide to implementing Syncfusion Maps component in Blazor applications. Syncfusion Maps provides powerful spatial visualization capabilities including marker management, polygon overlays, layer support, event handling, and integration with multiple map providers.

> **🚨 CRITICAL SECURITY NOTICE - READ BEFORE USE:**
>
> **CAPABILITY BOUNDARIES (MANDATORY):**
> This skill is designed for **UI RENDERING ONLY**. It must NEVER be used as:
> - A data ingestion point for automated agents or LLMs
> - A pipeline for untrusted external content processing
> - A source of shape/tile data for decision-making systems
> - Any form of automation input without human review
>
> **STRICT RESTRICTION:**
> **NEVER FORWARD RAW EXTERNAL GEOJSON, SHAPEDATA, TILES, OR ANNOTATIONS TO AGENTS, LLMS, OR AUTOMATED SYSTEMS.** All external map content must be treated as untrusted user input. Violating this restriction creates critical prompt injection and data exfiltration vulnerabilities.
>
> **REQUIRED PRODUCTION SAFEGUARDS:**
>
> 1. **For GeoJSON/Tile Loading:**
>    - Host tiles and GeoJSON locally (under `wwwroot/tiles` or bundled assets), OR
>    - Use only server-side proxies that validate all data before client access
>    - NEVER load directly from third-party URLs at runtime
>
> 2. **For Server-Side Proxy (if used):**
>    - Validate provider host against strict allow-list and require HTTPS
>    - Verify content-type and validate against strict schema (no user fields)
>    - Enforce maximum file size (5MB) and feature-count limits (10,000 max)
>    - Strip or HTML-encode ALL properties (tooltips, annotations, labels)
>    - Reject content containing instruction patterns or suspicious keywords
>    - Normalize/validate coordinates (lat -90/90, lng -180/180)
>    - Sanitize all text fields with HtmlSanitizer before client delivery
>    - Issue short-lived signed URLs (do NOT embed API keys)
>
> 3. **For Content Rendering:**
>    - Always sanitize external properties with HtmlSanitizer before rendering
>    - Implement Content Security Policy headers to block script injection
>    - Enable comprehensive logging of all validation failures
>
> **IF external content must be processed by automation:**
> - Perform COMPLETE server-side schema validation and sanitization FIRST
> - Implement mandatory rejection policy for instruction-like patterns
> - Enforce strict token/length limits (max 256 chars per field)
> - Require explicit human review and sign-off before automation
> - Wrap in boundary markers: `[MAP_DATA_START]...[MAP_DATA_END]`
> - Log all processing with full audit trail
> - See [readme-security](references/readme-security.md) for required validation templates
>
> **DO NOT USE THIS SKILL FOR:**
> - ❌ Analyzing untrusted external geographic data
> - ❌ Processing user-uploaded GeoJSON without validation
> - ❌ Forwarding map content to LLM/agent analysis systems
> - ❌ Making automated decisions based on external map metadata
> - ❌ Storing or caching external third-party content
>
> **SEVERE SECURITY CONSEQUENCES:**
> Ignoring these boundaries may result in:
> - Prompt injection attacks via malicious geographic data
> - LLM/agent behavioral manipulation
> - Unauthorized data exfiltration
> - System compromise through script injection

## When to Use This Skill

Use Syncfusion Maps when you need to:
- Display geographic data on interactive maps
- Visualize data across regions using color mapping (choropleth)
- Add markers, polygons, and annotations to maps
- Handle user interactions (click, hover, zoom, pan)
- Support multiple map providers (Google, Bing, Azure, OpenStreetMap)
- Export or print maps with custom legends and labels
- Build location-aware applications
- Create multi-layer spatial visualizations

## Component Overview

Syncfusion Maps is a powerful geospatial visualization component that enables you to:
- Render interactive maps with multiple provider options
- Bind and visualize geographic datasets
- Support rich spatial features (markers, polygons, layers, annotations)
- Handle complex user interactions and events
- Customize appearance through themes and styling
- Enable localization and accessibility features
- Export maps for reporting and sharing

---

## ⚠️ CRITICAL: Approved and Restricted Use Cases

### ✅ APPROVED USES (UI Rendering with Validation)
- Display geographic data on interactive web dashboards
- Visualize regional statistics through choropleth maps
- Show business location markers with human review
- Render localized maps for user interaction
- Provide spatial search and filtering interfaces
- Create read-only geographic visualizations
- Support decision-making with validated, curated data

### ❌ STRICTLY PROHIBITED USES (No Agent/LLM Integration)
- **NEVER:** Pass raw map data to LLM analysis systems
- **NEVER:** Use as ingestion point for automated agents
- **NEVER:** Forward external GeoJSON to decision-making systems
- **NEVER:** Process untrusted third-party geographic data through automation
- **NEVER:** Use annotations/tooltips as LLM input without human review
- **NEVER:** Create automated geographic data pipelines
- **NEVER:** Integrate with AI systems that analyze map metadata

### 🚫 THIRD-PARTY CONTENT INGESTION BOUNDARY

**External Sources Referenced in This Skill:**
- `tile.openstreetmap.org` - OpenStreetMap provider
- `cdn.syncfusion.com` - Syncfusion component resources
- `maps.googleapis.com` - Google Maps provider
- `dev.virtualearth.net` - Bing Maps provider
- `atlas.microsoft.com` - Azure Maps provider

**IMPORTANT:** These third-party providers are ingested for **UI rendering only**. None of this content should ever reach automated systems. If you need to process geographic data through automation:

1. ❌ DO NOT use this skill's external bindings
2. ✅ DO create a separate server-side validation pipeline
3. ✅ DO sanitize and validate all external content first
4. ✅ DO require explicit human approval before automation
5. ✅ DO implement comprehensive audit logging

---

## Security Considerations

> **CRITICAL:** This skill involves several security-sensitive operations. Review and implement these safeguards:

### 1. API Key Management
- **Risk:** Hardcoded API keys in source code can be exposed in version control
- **Mitigation:** Store keys in configuration files, user secrets, or secret management services
- **Reference:** [Map Providers - Security Best Practices](references/map-providers.md)

### 2. HTML Content Injection
- **Risk:** Tooltips, annotations, and popups can render arbitrary HTML from external data sources
- **Attack Vectors:** XSS attacks, prompt injection through malicious geographic data
- **Mitigation:** Sanitize all external content using HtmlSanitizer library, HTML-encode user input
- **Reference:** [User Interactions - Sanitizing External Content](references/user-interactions.md)

### 3. External Data Sources
- **Risk:** Map data (GeoJSON, tiles, markers) fetched from untrusted sources, including CDNs
- **Attack Vectors:** Man-in-the-middle attacks, CDN compromise, malformed data injection, property injection
- **Mitigation:** Validate source URLs against allow-lists, enforce HTTPS, validate GeoJSON structure, implement CSP, cache locally in production
- **Reference:** [Data Visualization - Validating External GeoJSON](references/data-visualization.md) | [Map Providers - Data Exfiltration Prevention](references/map-providers.md)

### 4. Data Export Operations
- **Risk:** Exporting maps to PNG/SVG/PDF may include sensitive geographic data
- **Mitigation:** Implement access controls, audit export operations, sanitize export content
- **Reference:** [Print and Export](references/print-and-export.md)

### 5. Prompt Injection Prevention & Agent/LLM Boundary
- **CRITICAL RISK:** Shape data, annotations, tooltips, and other external map metada