With Claude

Fix AnimationTool CSP Violation with STAC Layers

Problem

When using the AnimationTool with STAC collection layers enabled, the browser threw a Content Security Policy (CSP) error:

Loading the image 'stac-collection:monthly_10km?datetime=2024-12-01T00:00:00.000Z/2024-12-31T23:59:59.000Z&exitwhenfull=false&skipcovered=false&rescale=[0,0.5]&colormap_name=jet' violates the following Content Security Policy directive: "img-src * data: blob: 'unsafe-inline'". Note that '*' matches only URLs with network schemes ('http', 'https', 'ws', 'wss'), or URLs whose scheme matches `self`'s scheme. The scheme 'stac-collection:' must be added explicitly.

Root Cause

The stac-collection: URL scheme is a custom MMGIS notation that must be transformed into a proper HTTP URL before being passed to browser image loading functions. While this transformation existed for tile layers in makeTileLayer(), it was missing from L_.getUrl(), which is called by makeImageLayer() and other layer functions. This issue was exposed by recent AnimationTool OffscreenMapManager changes (#856, #857).

Solution

Transform stac-collection: URLs into proper TiTiler PgSTAC HTTP endpoints before they reach the browser's image loading functions. This is accomplished by:

1. Creating a shared transformStacUrl() function in Layers_.js
2. Using it consistently in both L_.getUrl() and makeTileLayer()
3. Ensuring all layer types (tile and image) properly transform STAC URLs

Changes

1. Added transformStacUrl() Function

File: src/essence/Basics/Layers_/Layers_.js

Created a new exported function that:

• Detects stac-collection: URLs (case-insensitive)
• Parses collection name and parameters
• Builds proper TiTiler PgSTAC endpoints:
  • Tiles: /titilerpgstac/collections/{collection}/tiles/{tileMatrixSet}/{z}/{x}/{y}?assets=asset...
  • Images: /titilerpgstac/collections/{collection}/preview?assets=asset...
• Handles parameters: cogBands, cogExpression, cogResampling, tileMatrixSet
• Logs warnings when STAC layers are configured as image type (they work best as tiles)

2. Updated L_.getUrl() Method

File: src/essence/Basics/Layers_/Layers_.js

Modified to use the new transformStacUrl() function for STAC URLs. This automatically fixes:

• makeImageLayer() - which calls L_.getUrl()
• Any other code that uses L_.getUrl() for URL resolution

3. Refactored makeTileLayer()

File: src/essence/Basics/Map_/Map_.js

Updated to import and use the shared transformStacUrl() function instead of inline transformation logic. This:

• Eliminates code duplication
• Ensures consistent STAC URL handling across the codebase
• Simplifies future maintenance

4. Added Comprehensive Tests

File: tests/unit/stac-url-transformation.spec.js (NEW)

Created 19 unit tests covering:

• Basic URL transformation for tiles and images
• Parameter handling (bands, resampling, tileMatrixSet)
• Expression priority over bands
• Edge cases (null data, empty bands, malformed URLs)
• Case-insensitive detection
• Non-STAC URL preservation

Example Transformation

Input:

stac-collection:monthly_10km

Output (tiles):

http://localhost:8888/titilerpgstac/collections/monthly_10km/tiles/WebMercatorQuad/{z}/{x}/{y}?assets=asset

Output (images):

http://localhost:8888/titilerpgstac/collections/monthly_10km/preview?assets=asset

Testing

Unit Tests

• ✅ All 241 unit tests pass (including 19 new STAC transformation tests)
• ✅ Tests cover normal cases, edge cases, and error conditions
• ✅ No regressions in existing tests

Build

• ✅ Production build completes successfully
• ✅ No TypeScript or linting errors

Manual Testing Recommended

To verify the fix works end-to-end:

1. Setup: Ensure WITH_STAC=true in .env and configure a STAC collection layer
2. Test AnimationTool:
   • Enable STAC layer visibility
   • Open AnimationTool and create an animation
   • Check browser console for CSP errors (should be none)
3. Verify Network Requests:
   • Open DevTools Network tab
   • Confirm URLs match pattern: /titilerpgstac/collections/{name}/...
   • Confirm no stac-collection: URLs are being fetched

Impact

• Fixes: CSP violation in AnimationTool with STAC layers
• Improves: Code maintainability through DRY principle
• Maintains: Full backward compatibility with existing STAC tile layers
• Affects: Any code that creates map layers with STAC collection URLs

Related Issues

• Exposed by AnimationTool OffscreenMapManager refactoring ([Bug]: AnimationTool outputs is warped in non-mercator projections #856, #856 AnimationTool Improvements #857)
• May benefit other tools that create independent map instances

Breaking Changes

None. This is a bug fix that maintains backward compatibility.